Backend Service (Core)

Purpose

The Core Backend Service is the central nervous system of the L-AGE Web Tool. It serves as the primary API gateway for the frontend, handling authentication, user management, and core application logic such as the internal task management system. It also enforces security policies like rate limiting and centralized logging.

High-Level Architecture

This service runs as a Docker container (backend) and exposes an HTTP API on port 8000.

• Upstream: Receives requests from the Frontend (React) or external clients.
• Downstream:
• Postgres: Stores users, tasks, and authentication data.
• Discord: Sends notifications for task updates (via webhooks).
• Siblings: It co-exists with other microservices (service-invoice, service-multi-repricer, etc.) but primarily handles "core" platform features rather than domain-specific business logic.

Configuration & Environment Variables

The service is configured via environment variables (loaded from .env).

Variable	Default	Description
DATABASE_URL	postgresql://...	Connection string for the Postgres database.
SECRET_KEY	your-secret-key...	Key used for signing JWT tokens. Must be changed in production.
ALGORITHM	HS256	Algorithm used for JWT signing.
ACCESS_TOKEN_EXPIRE_MINUTES	120	Token validity duration in minutes.
ADMIN_USERNAME	admin	Username for the default superuser created on startup.
ADMIN_PASSWORD	Admin123!	Password for the default superuser.
DEV_MODE	false	Toggles development-specific features (e.g., verbose logging).

Database Schema

The core service manages the following key entities in the enterprisedb database:

Users (users table)

Represents system administrators and staff members.

• Key Fields: username, email, hashed_password, is_superuser.
• Integrations: discord_username, discord_webhook (for notifications).

Tasks (tasks table)

Represents the internal ticketing/todo items.

• Key Fields: title, description, status (todo/in_progress/done), priority (low/medium/high/urgent).
• Relationships:
• created_by_id -> User (One-to-Many)
• assignee_id -> User (One-to-Many)
• mentioned_users -> User (Many-to-Many via task_mentions table)

Application Structure

The codebase follows a standard FastAPI layered architecture:

• main.py: The application entry point. Configures middleware (CORS, Rate Limiting, Logging) and includes routers.
• api/v1/: Contains the API route definitions.
• endpoints/: Specific route handlers grouped by domain (auth, users, tasks).
• core/: Configuration, database connection logic, and security settings.
• services/: Business logic layer (e.g., AuthService, UserService) that orchestrates operations between the API and the database.
• crud/: Data access layer containing raw database queries.
• models/: SQLAlchemy ORM models representing database tables.
• schemas/: Pydantic models for request/response validation.

Security & Authentication

Authentication Mechanism

The service uses OAuth2 with Password Flow and JWT (JSON Web Tokens).

1. Login: Client sends username and password to /api/v1/auth/login.
2. Verification: AuthService verifies the password hash (using bcrypt).
3. Token Issue: A signed JWT is returned containing the user's identity (sub) and expiration time.
4. Access: Subsequent requests must include the header Authorization: Bearer <token>.

Rate Limiting

To prevent abuse, a custom in-memory rate limiter is implemented in main.py.

• Limit: 100 requests per 60 seconds per IP address.
• Implementation: Uses a sliding window algorithm stored in a defaultdict.
• Exclusions: WebSocket endpoints (/ws) are excluded from rate limiting.

FastAPI Routers

1. Authentication (/api/v1/auth)

Handles user login and token generation.

• POST /login: Authenticates a user via username/password and returns a JWT access token.

2. Users (/api/v1/users)

Manages user accounts and profiles.

• GET /me: Returns the currently authenticated user's profile.
• PUT /me: Updates the current user's profile.
• POST /: Creates a new user (Admin only).
• GET /{user_id}: Retrieves details of a specific user.

3. Tasks (/api/v1/tasks)

Implements the internal task/ticketing system.

• GET /: Lists tasks visible to the user (created by, assigned to, or mentioned in).
• POST /: Creates a new task.
• GET /assigned: Lists tasks assigned specifically to the current user.
• GET /mentioned: Lists tasks where the current user is mentioned.

Key Workflows

Authentication Flow

When a user logs in, the system validates credentials against the database and issues a stateless JWT token.

graph TD Client[Client] -->|POST /login| API[FastAPI Endpoint] API -->|Validate Credentials| AuthService[Auth Service] AuthService -->|Query User| DB[(Postgres)] DB -->|User Record| AuthService AuthService -->|Verify Password Hash| AuthService AuthService -->|Generate JWT| API API -->|Return Access Token| Client

Task Creation & Notification

When a task is created, the system saves it to the database and checks for user mentions to send external notifications (e.g., to Discord).

graph TD Client[Client] -->|POST /tasks| API[FastAPI Endpoint] API -->|Validate Token| Auth[Auth Middleware] Auth -->|User Context| API API -->|Create Task Object| CRUD[Task CRUD] CRUD -->|Insert Task| DB[(Postgres)] CRUD -->|Check Mentions| Logic[Notification Logic] Logic -->|Found Mentions?| Discord[Send Discord Webhook] Logic -->|No Mentions| End[Finish]

Rate Limiting

To prevent abuse, a custom middleware tracks request frequency by IP address.

graph TD Request[Incoming Request] --> Middleware[Rate Limit Middleware] Middleware -->|Check IP History| Memory[In-Memory Store] Memory -->|Count < Limit| Allow[Pass to Router] Memory -->|Count > Limit| Block[Return 429 Error]