Architecture

Layered design

flowchart LR
  HTTP[HTTP_Client]
  R[routers]
  S[services]
  P[PermissionService]
  Rep[repositories]
  DB[(PostgreSQL)]

  HTTP --> R --> S --> Rep --> DB
  S --> P

JWT flow

sequenceDiagram
  participant C as Client
  participant A as AuthRouter
  participant S as AuthService
  participant DB as PostgreSQL

  C->>A: POST /auth/login (OAuth2 form, username = email)
  A->>S: authenticate_user
  S->>DB: load active user by email
  S-->>A: User or failure
  A->>S: create_access_token(sub=email)
  Note over S: exp / iat as Unix timestamps (UTC)
  A-->>C: access_token + bearer type

  C->>A: Protected route + Authorization Bearer
  A->>S: decode_token_payload + TokenPayload validation
  A->>DB: resolve user by sub (email), check is_active

ER diagram (conceptual)

erDiagram
  USER ||--o{ TEAM_MEMBER : joins
  TEAM ||--o{ TEAM_MEMBER : has
  USER ||--o{ TEAM : owns
  TEAM ||--o{ TASK : contains
  USER ||--o{ TASK : creates
  USER ||--o{ TASK : assigned_optional

  USER {
    int id PK
    string email UK
    string username UK
    bool is_active
    datetime created_at
    datetime updated_at
    datetime deleted_at
  }

  TEAM {
    int id PK
    string name UK
    string description
    int owner_id FK
    datetime created_at
    datetime updated_at
    datetime deleted_at
  }

  TEAM_MEMBER {
    int user_id PK_FK
    int team_id PK_FK
    enum role
  }

  TASK {
    int id PK
    string title
    string description
    string status
    string priority
    int team_id FK
    int created_by FK
    int assigned_to FK
    datetime created_at
    datetime updated_at
    datetime deleted_at
  }

Configuration & environments

Settings load environment variables first, then optional env files:

1. .env.{APP_ENV} (for example .env.prod when APP_ENV=prod)
2. .env

Templates (safe to commit):

• .env.example
• .env.dev.example
• .env.prod.example

Local development

python3 -m venv .venv
source .venv/bin/activate         
pip install -r requirements.txt

docker compose up -d db            # PostgreSQL on localhost:5432
export DATABASE_URL=postgresql+psycopg://taskuser:taskpass@localhost:5432/task_manager
alembic upgrade head
uvicorn app.main:app --reload

Interactive docs: http://localhost:8000/docs

Full stack (API + DB)

docker compose up --build

The API container runs alembic upgrade head before starting Uvicorn.

Alembic

alembic revision --autogenerate -m "describe change"
alembic upgrade head
alembic downgrade -1

alembic/env.py reads DATABASE_URL from application settings, so Docker/Railway/CI stay aligned without editing alembic.ini.

Example HTTP calls

Register:

curl -s -X POST http://localhost:8000/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"alice@example.com","username":"alice","password":"password123"}'

Login (OAuth2 password flow — username must be the email):

curl -s -X POST http://localhost:8000/auth/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=alice@example.com&password=password123'

Create a team (Bearer token):

curl -s -X POST http://localhost:8000/teams/ \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Platform","description":"Core services"}'

Paginated & filtered tasks:

curl -s "http://localhost:8000/tasks/team/1?page=1&limit=20&status=done" \
  -H "Authorization: Bearer $TOKEN"

Testing & linting

Requires PostgreSQL (tests default to task_manager_test).

createdb dark_moon_test   # once
export DATABASE_URL=postgresql+psycopg://taskuser:taskpass@localhost:5432/task_manager_test
pytest -q
ruff check app alembic tests

Observability

• Structured stdout logging configured via LOG_LEVEL.
• GET /health — process up.
• GET /health/ready — verifies database connectivity (SELECT 1).

Deploy on Railway

1. Create a Railway project from this repo.
2. Add the PostgreSQL plugin and copy the generated DATABASE_URL.
3. Set service variables: SECRET_KEY, DATABASE_URL, ACCESS_TOKEN_EXPIRE_MINUTES, APP_ENV=prod, LOG_LEVEL=INFO.
4. Railway invokes railway.toml startCommand, which applies migrations then launches Uvicorn on PORT.

GitHub Actions

.github/workflows/ci.yml installs dependencies, runs Ruff, applies Alembic migrations against a PostgreSQL 16 service, and executes pytest.

Project layout

Security notes

• Never commit real .env files or database passwords.
• Rotate SECRET_KEY for every environment.
• GET /teams/{id} requires team membership (IDs are not enumerable anonymously).

Licensed for portfolio / educational use unless otherwise stated.