flowchart LR
    subgraph Client["Browser"]
        FE["React + Vite SPA<br/>(port 5173)"]
    end

    subgraph API["FastAPI Application (port 8000)"]
        direction TB
        MW["Auth dependency<br/>get_current_user / require_role"]
        R["Routers<br/>(HTTP + guards, thin)"]
        S["Services<br/>(business logic, transactions,<br/>conflict rules)"]
        M["Models (SQLAlchemy) +<br/>Schemas (Pydantic)"]
        MW --> R --> S --> M
    end

    subgraph DB["PostgreSQL 16"]
        direction TB
        EXT["Extensions:<br/>pgcrypto · btree_gist · citext"]
        TBL["Tables + Postgres enums"]
        CON["Constraints:<br/>one_active_allocation_per_asset (unique)<br/>no_overlapping_bookings (GIST exclude)"]
    end

    FE -- "JSON + JWT bearer token" --> MW
    M -- "SQLAlchemy" --> TBL
    TBL --- CON
    TBL --- EXT

sequenceDiagram
    participant U as Employee/Manager (browser)
    participant R as routers/allocation.py
    participant D as deps.py (auth guard)
    participant S as services/allocation_service.py
    participant DB as PostgreSQL

    U->>R: POST /api/allocations {asset_id, holder_user_id}
    R->>D: get_current_user(token)
    D-->>R: current_user (id, role, department_id)
    R->>D: require_role(ADMIN, ASSET_MANAGER, DEPARTMENT_HEAD)
    D-->>R: 403 if role not permitted (request ends)
    R->>S: allocate(db, data, actor)
    S->>DB: SELECT active allocation WHERE asset_id = ...
    alt asset already allocated
        DB-->>S: existing ACTIVE row
        S-->>R: 409 asset_already_allocated + current_holder + suggested_action
        R-->>U: 409 (friendly conflict body)
    else asset free
        DB-->>S: none
        S->>DB: INSERT allocation (ACTIVE)
        S->>DB: UPDATE asset.status = ALLOCATED
        S->>DB: INSERT activity_logs("asset.allocated")
        S->>DB: INSERT notifications(ASSET_ASSIGNED)
        DB-->>S: commit
        S-->>R: AllocationOut
        R-->>U: 200 allocation created
    end

erDiagram
    DEPARTMENTS ||--o{ USERS : "has members"
    DEPARTMENTS ||--o| DEPARTMENTS : "parent (self-ref)"
    USERS ||--o| DEPARTMENTS : "heads (optional)"
    ASSET_CATEGORIES ||--o{ ASSETS : "categorizes"
    ASSETS ||--o{ ALLOCATIONS : "allocation history"
    ASSETS ||--o{ TRANSFER_REQUESTS : "transfer history"
    ASSETS ||--o{ BOOKINGS : "booking calendar"
    ASSETS ||--o{ MAINTENANCE_REQUESTS : "maintenance history"
    ASSETS ||--o{ AUDIT_ITEMS : "audited in cycles"
    USERS ||--o{ ALLOCATIONS : "holds / allocates"
    USERS ||--o{ TRANSFER_REQUESTS : "from / to / requested_by"
    USERS ||--o{ BOOKINGS : "books"
    USERS ||--o{ MAINTENANCE_REQUESTS : "raises"
    USERS ||--o{ NOTIFICATIONS : "receives"
    USERS ||--o{ ACTIVITY_LOGS : "acts"
    AUDIT_CYCLES ||--o{ AUDIT_ITEMS : "snapshots assets"
    AUDIT_CYCLES }o--o{ USERS : "assigned auditors"

    USERS {
        uuid id PK
        text name
        citext email UK
        text password_hash
        user_role role
        uuid department_id FK
        active_status status
    }

    DEPARTMENTS {
        uuid id PK
        text name UK
        uuid head_user_id FK
        uuid parent_department_id FK
        active_status status
    }

    ASSET_CATEGORIES {
        uuid id PK
        text name UK
        jsonb custom_fields
    }

    ASSETS {
        uuid id PK
        text asset_tag UK "AF-0001, sequence-generated"
        text name
        uuid category_id FK
        text serial_number UK
        asset_condition condition
        boolean is_bookable
        jsonb custom_values
        asset_status status "lifecycle state"
    }

    ALLOCATIONS {
        uuid id PK
        uuid asset_id FK
        uuid holder_user_id FK
        uuid holder_department_id FK
        uuid allocated_by FK
        date expected_return_date
        timestamptz returned_at
        allocation_status status
    }

    TRANSFER_REQUESTS {
        uuid id PK
        uuid asset_id FK
        uuid from_user_id FK
        uuid to_user_id FK
        uuid requested_by FK
        transfer_status status
        uuid approved_by FK
    }

    BOOKINGS {
        uuid id PK
        uuid asset_id FK
        uuid booked_by_user_id FK
        uuid department_id FK
        tstzrange time_range "half-open [start,end)"
        booking_status status
    }

    MAINTENANCE_REQUESTS {
        uuid id PK
        uuid asset_id FK
        uuid raised_by FK
        maintenance_priority priority
        maintenance_status status
        uuid approved_by FK
        text technician_name
    }

    AUDIT_CYCLES {
        uuid id PK
        text name
        uuid scope_department_id FK
        date start_date
        date end_date
        audit_cycle_status status
        uuid created_by FK
        timestamptz closed_at
    }

    AUDIT_ITEMS {
        uuid id PK
        uuid audit_cycle_id FK
        uuid asset_id FK
        text expected_location
        audit_verification verification
        uuid verified_by FK
    }

    NOTIFICATIONS {
        uuid id PK
        uuid recipient_user_id FK "null = broadcast"
        notification_type type
        text message
        boolean is_read
    }

    ACTIVITY_LOGS {
        uuid id PK
        uuid actor_user_id FK
        text action "namespaced, e.g. asset.allocated"
        jsonb metadata
    }

sequenceDiagram
    participant U as User
    participant Auth as /auth endpoints
    participant Sec as security.py
    participant Dep as deps.py

    U->>Auth: POST /auth/signup {name, email, password}
    Note over Auth: role field ignored/rejected —<br/>signup always creates EMPLOYEE
    Auth->>Sec: bcrypt hash password
    Sec-->>Auth: password_hash
    Auth-->>U: 201 user created (role = EMPLOYEE)

    U->>Auth: POST /auth/login {email, password}
    Auth->>Sec: verify bcrypt hash
    Sec->>Sec: encode JWT {sub: user_id, role, department_id, exp: +8h}
    Sec-->>Auth: access_token
    Auth-->>U: {access_token, token_type, user}

    U->>Dep: any /api/* request with bearer token
    Dep->>Dep: decode JWT, load user, check status == ACTIVE
    Dep-->>U: 401 if invalid/expired/inactive
    Dep->>Dep: require_role(*roles) — 403 if role not in allowed set
    Note over Dep: Department Head scoping is a service-layer<br/>comparison of current_user.department_id,<br/>not a JWT claim check

stateDiagram-v2
    [*] --> AVAILABLE: register
    AVAILABLE --> ALLOCATED: allocate
    ALLOCATED --> AVAILABLE: return
    ALLOCATED --> ALLOCATED: transfer approved (holder changes)
    AVAILABLE --> UNDER_MAINTENANCE: maintenance request approved
    UNDER_MAINTENANCE --> AVAILABLE: maintenance resolved
    AVAILABLE --> RETIRED: admin action
    RETIRED --> DISPOSED: admin action
    ALLOCATED --> LOST: audit cycle closed, item = MISSING
    AVAILABLE --> LOST: audit cycle closed, item = MISSING
    UNDER_MAINTENANCE --> LOST: audit cycle closed, item = MISSING

flowchart TD
    Start(["POST /allocations<br/>{asset_id, holder}"]) --> Check{"Active allocation<br/>exists for asset?"}
    Check -- yes --> Conflict["409 asset_already_allocated<br/>+ current_holder + suggested_action: transfer_request"]
    Check -- no --> Insert["INSERT allocation (ACTIVE)<br/>UPDATE asset.status = ALLOCATED<br/>log + notify holder"]
    Conflict --> Transfer(["POST /transfers<br/>{asset_id, to_user_id}"])
    Transfer --> TReq["INSERT transfer_request (REQUESTED)"]
    TReq --> Approve{"Asset Mgr / Dept Head<br/>approves?"}
    Approve -- reject --> TRej["transfer.status = REJECTED<br/>notify requester"]
    Approve -- approve --> Atomic["Single transaction:<br/>close old allocation (RETURNED)<br/>open new allocation (ACTIVE) to new holder<br/>transfer.status = COMPLETED<br/>log asset.transferred, notify both parties"]
    Insert --> End(["asset.status = ALLOCATED"])
    Atomic --> End

flowchart TD
    Start(["POST /bookings<br/>{asset_id, start, end}"]) --> Bookable{"asset.is_bookable?"}
    Bookable -- no --> E422["422 — not a bookable asset"]
    Bookable -- yes --> Overlap{"Non-cancelled booking on<br/>this asset with<br/>time_range && requested_range?"}
    Overlap -- yes --> E409["409 booking_overlap<br/>+ conflicting_booking{id,start,end}"]
    Overlap -- no --> Ins["INSERT booking (UPCOMING)<br/>log booking.created<br/>notify BOOKING_CONFIRMED"]
    Ins --> DBConstraint["GIST exclusion constraint re-validates<br/>at commit — final guarantee"]

stateDiagram-v2
    [*] --> PENDING: raise request
    PENDING --> APPROVED: asset_mgr+ approves\n(asset → UNDER_MAINTENANCE)
    PENDING --> REJECTED: asset_mgr+ rejects
    APPROVED --> TECHNICIAN_ASSIGNED: assign technician
    TECHNICIAN_ASSIGNED --> IN_PROGRESS: work starts
    IN_PROGRESS --> RESOLVED: resolved\n(asset → AVAILABLE)

flowchart TD
    Create(["POST /audit-cycles<br/>(Admin)"]) --> Snapshot["Snapshot in-scope assets<br/>into audit_items (PENDING,<br/>expected_location captured)"]
    Snapshot --> Assign["POST /audit-cycles/{id}/auditors<br/>assign users as auditors"]
    Assign --> Mark["PATCH /audit-items/{id}<br/>assigned auditor (or Admin/Asset Mgr) sets<br/>VERIFIED | MISSING | DAMAGED"]
    Mark --> Close["POST /audit-cycles/{id}/close (Admin)<br/>cycle.status = CLOSED"]
    Close --> Discrepancy["Auto-generate discrepancy report:<br/>every MISSING item → asset.status = LOST<br/>AUDIT_DISCREPANCY notification per discrepancy"]

flowchart TB
    subgraph Compose["docker compose up -d --build"]
        direction LR
        subgraph pg["postgres (assetflow-db)"]
            PGV[("pgdata volume")]
        end
        subgraph api["api (assetflow-api)"]
            direction TB
            Mig["alembic upgrade head"]
            Seed["python -m app.seed.seed"]
            Uv["uvicorn --reload"]
            Mig --> Seed --> Uv
        end
        subgraph fe["frontend (assetflow-frontend)"]
            Vite["vite dev --host 0.0.0.0"]
        end
        api -- "depends_on: service_healthy" --> pg
        fe -- "depends_on" --> api
    end

    Dev["Developer machine"] -- "bind mount ./backend:/app<br/>hot reload" --> api
    Dev -- "bind mount ./frontend:/app<br/>(node_modules stays in image)" --> fe
    Browser["localhost:5173"] --> fe
    Browser -. "REST calls" .-> api
    api -- "5432" --> pg