# allanlugui/facil architecture

> Architecture diagram of the GitHub repository allanlugui/facil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/allanlugui/facil
- Repository: https://github.com/allanlugui/facil

## Overview

Facil is an internal facilities-management platform. Staff use a React interface to manage facilities and operational workflows; the client sends API requests to a Cloudflare Worker, which enforces access and persists domain changes in D1. The documented purchasing workflow is a distinct staged process, alongside inventory, assets, service operations, administration, and reporting. The README documents optional R2 attachments, real-time support, and external integrations. Several routes were not sampled, so their internal calls are not inferred.

Main entry points: [`src/worker/index.ts`](https://github.com/allanlugui/facil/blob/main/src/worker/index.ts) (Worker entry), [`src/client/lib/api.ts`](https://github.com/allanlugui/facil/blob/main/src/client/lib/api.ts) (API client), [`src/client/app/router.tsx`](https://github.com/allanlugui/facil/blob/main/src/client/app/router.tsx) (App router), [`src/worker/auth.ts`](https://github.com/allanlugui/facil/blob/main/src/worker/auth.ts) (Session and permissions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client application"]
  node_router["App router<br/>[router.tsx]"]
  node_session["Session state<br/>[session.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_dashboard["Dashboard<br/>[dashboard.tsx]"]
  node_purchases_ui["Purchasing UI<br/>[purchases.tsx]"]
  node_assets_ui["Asset UI<br/>[assets.tsx]"]
  node_workorders_ui["Work orders UI<br/>[workorders.tsx]"]
  node_domain_pages["Operations pages"]
end

subgraph group_api["Worker API"]
  node_worker["Worker entry<br/>[index.ts]"]
end

subgraph group_operations["Facilities operations"]
  node_purchase_routes["Purchase workflow<br/>[purchases.ts]"]
  node_asset_routes["Asset management<br/>[assets.ts]"]
  node_workorder_routes["Work orders<br/>[workorders.ts]"]
  node_other_routes["Domain routes"]
  node_support["Support chat<br/>[chat.tsx]"]
  node_reports["Reports and exports<br/>[reports.ts]"]
end

subgraph group_governance["Administration and governance"]
  node_auth_routes["Authentication<br/>[auth.ts]"]
  node_settings_routes["Settings<br/>[settings.ts]"]
  node_auth["Session and permissions<br/>[auth.ts]"]
  node_audit["Audit trail<br/>[audit.ts]"]
end

subgraph group_platform["Persistence and integrations"]
  node_db_helpers["Database helpers<br/>[db.ts]"]
  node_d1[("D1 database")]
  node_outbox["Integration outbox<br/>[outbox.ts]"]
  node_support_room["Realtime support room<br/>[support-room.ts]"]
  node_r2[("Optional attachments")]
end

node_staff(("Staff user"))
node_external_systems["External systems"]

node_staff -->|"uses"| node_router
node_router -->|"checks session"| node_session
node_router -->|"routes to"| node_dashboard
node_router -->|"routes to"| node_purchases_ui
node_router -->|"routes to"| node_assets_ui
node_staff -.->|"uses"| node_domain_pages
node_purchases_ui -->|"calls"| node_api_client
node_assets_ui -->|"calls"| node_api_client
node_workorders_ui -->|"calls"| node_api_client
node_dashboard -->|"calls"| node_api_client
node_session -->|"calls"| node_api_client
node_api_client -.->|"HTTP requests"| node_worker
node_worker -->|"registers"| node_purchase_routes
node_worker -->|"registers"| node_auth_routes
node_worker -->|"registers"| node_settings_routes
node_worker -->|"registers"| node_asset_routes
node_worker -->|"registers"| node_workorder_routes
node_worker -.->|"registers"| node_other_routes
node_purchase_routes -->|"uses access"| node_auth
node_purchase_routes -->|"uses helpers"| node_db_helpers
node_purchase_routes -->|"writes events"| node_outbox
node_asset_routes -->|"uses access"| node_auth
node_asset_routes -->|"uses helpers"| node_db_helpers
node_asset_routes -->|"records changes"| node_audit
node_workorder_routes -->|"uses helpers"| node_db_helpers
node_workorder_routes -->|"records changes"| node_audit
node_auth_routes -->|"creates sessions"| node_auth
node_auth_routes -->|"records events"| node_audit
node_settings_routes -->|"checks access"| node_auth
node_settings_routes -->|"records changes"| node_audit
node_auth -->|"stores sessions"| node_d1
node_db_helpers -.->|"reads and writes"| node_d1
node_audit -->|"writes audit log"| node_d1
node_reports -.->|"queries reports"| node_d1
node_support -.->|"realtime chat"| node_support_room
node_support -.->|"stores attachments"| node_r2
node_outbox -.->|"dispatches events"| node_external_systems

click node_router "https://github.com/allanlugui/facil/blob/main/src/client/app/router.tsx"
click node_session "https://github.com/allanlugui/facil/blob/main/src/client/lib/session.tsx"
click node_api_client "https://github.com/allanlugui/facil/blob/main/src/client/lib/api.ts"
click node_dashboard "https://github.com/allanlugui/facil/blob/main/src/client/pages/dashboard.tsx"
click node_purchases_ui "https://github.com/allanlugui/facil/blob/main/src/client/pages/purchases.tsx"
click node_assets_ui "https://github.com/allanlugui/facil/blob/main/src/client/pages/assets.tsx"
click node_workorders_ui "https://github.com/allanlugui/facil/blob/main/src/client/pages/workorders.tsx"
click node_domain_pages "https://github.com/allanlugui/facil/tree/main/src/client/pages"
click node_worker "https://github.com/allanlugui/facil/blob/main/src/worker/index.ts"
click node_purchase_routes "https://github.com/allanlugui/facil/blob/main/src/worker/routes/purchases.ts"
click node_asset_routes "https://github.com/allanlugui/facil/blob/main/src/worker/routes/assets.ts"
click node_workorder_routes "https://github.com/allanlugui/facil/blob/main/src/worker/routes/workorders.ts"
click node_other_routes "https://github.com/allanlugui/facil/tree/main/src/worker/routes"
click node_auth_routes "https://github.com/allanlugui/facil/blob/main/src/worker/routes/auth.ts"
click node_settings_routes "https://github.com/allanlugui/facil/blob/main/src/worker/routes/settings.ts"
click node_auth "https://github.com/allanlugui/facil/blob/main/src/worker/auth.ts"
click node_audit "https://github.com/allanlugui/facil/blob/main/src/worker/audit.ts"
click node_db_helpers "https://github.com/allanlugui/facil/blob/main/src/worker/db.ts"
click node_outbox "https://github.com/allanlugui/facil/blob/main/src/worker/outbox.ts"
click node_support "https://github.com/allanlugui/facil/blob/main/src/client/lib/chat.tsx"
click node_support_room "https://github.com/allanlugui/facil/blob/main/src/worker/support-room.ts"
click node_reports "https://github.com/allanlugui/facil/blob/main/src/worker/routes/reports.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router,node_session,node_api_client,node_dashboard,node_purchases_ui,node_assets_ui,node_workorders_ui,node_domain_pages,node_staff toneBlue
class node_worker toneAmber
class node_purchase_routes,node_asset_routes,node_workorder_routes,node_other_routes,node_support,node_reports toneMint
class node_auth_routes,node_settings_routes,node_auth,node_audit toneRose
class node_db_helpers,node_d1,node_outbox,node_support_room,node_r2,node_external_systems toneIndigo
```

## Components

### Client application

- [App router](https://github.com/allanlugui/facil/blob/main/src/client/app/router.tsx): `src/client/app/router.tsx`
- [Session state](https://github.com/allanlugui/facil/blob/main/src/client/lib/session.tsx): `src/client/lib/session.tsx`
- [API client](https://github.com/allanlugui/facil/blob/main/src/client/lib/api.ts): `src/client/lib/api.ts`
- [Dashboard](https://github.com/allanlugui/facil/blob/main/src/client/pages/dashboard.tsx): `src/client/pages/dashboard.tsx`
- [Purchasing UI](https://github.com/allanlugui/facil/blob/main/src/client/pages/purchases.tsx): `src/client/pages/purchases.tsx`
- [Asset UI](https://github.com/allanlugui/facil/blob/main/src/client/pages/assets.tsx): `src/client/pages/assets.tsx`
- [Work orders UI](https://github.com/allanlugui/facil/blob/main/src/client/pages/workorders.tsx): `src/client/pages/workorders.tsx`
- [Operations pages](https://github.com/allanlugui/facil/tree/main/src/client/pages): `src/client/pages`

### Worker API

- [Worker entry](https://github.com/allanlugui/facil/blob/main/src/worker/index.ts): `src/worker/index.ts`

### Facilities operations

- [Purchase workflow](https://github.com/allanlugui/facil/blob/main/src/worker/routes/purchases.ts): `src/worker/routes/purchases.ts`
- [Asset management](https://github.com/allanlugui/facil/blob/main/src/worker/routes/assets.ts): `src/worker/routes/assets.ts`
- [Work orders](https://github.com/allanlugui/facil/blob/main/src/worker/routes/workorders.ts): `src/worker/routes/workorders.ts`
- [Domain routes](https://github.com/allanlugui/facil/tree/main/src/worker/routes): `src/worker/routes`
- [Support chat](https://github.com/allanlugui/facil/blob/main/src/client/lib/chat.tsx): `src/client/lib/chat.tsx`
- [Reports and exports](https://github.com/allanlugui/facil/blob/main/src/worker/routes/reports.ts): `src/worker/routes/reports.ts`

### Administration and governance

- [Authentication](https://github.com/allanlugui/facil/blob/main/src/worker/routes/auth.ts): `src/worker/routes/auth.ts`
- [Settings](https://github.com/allanlugui/facil/blob/main/src/worker/routes/settings.ts): `src/worker/routes/settings.ts`
- [Session and permissions](https://github.com/allanlugui/facil/blob/main/src/worker/auth.ts): `src/worker/auth.ts`
- [Audit trail](https://github.com/allanlugui/facil/blob/main/src/worker/audit.ts): `src/worker/audit.ts`

### Persistence and integrations

- [Database helpers](https://github.com/allanlugui/facil/blob/main/src/worker/db.ts): `src/worker/db.ts`
- **D1 database**
- [Integration outbox](https://github.com/allanlugui/facil/blob/main/src/worker/outbox.ts): `src/worker/outbox.ts`
- [Realtime support room](https://github.com/allanlugui/facil/blob/main/src/worker/support-room.ts): `src/worker/support-room.ts`
- **Optional attachments**

### Other components

- **Staff user**
- **External systems**

## Connections

- Staff user → App router: uses (evidence: `src/client/app/router.tsx`)
- App router → Session state: checks session (evidence: `src/client/app/router.tsx`)
- App router → Dashboard: routes to (evidence: `src/client/app/router.tsx`)
- App router → Purchasing UI: routes to (evidence: `src/client/app/router.tsx`)
- App router → Asset UI: routes to (evidence: `src/client/app/router.tsx`)
- Staff user → Operations pages: uses
- Purchasing UI → API client: calls (evidence: `src/client/pages/purchases.tsx`)
- Asset UI → API client: calls (evidence: `src/client/pages/assets.tsx`)
- Work orders UI → API client: calls (evidence: `src/client/pages/workorders.tsx`)
- Dashboard → API client: calls (evidence: `src/client/pages/dashboard.tsx`)
- Session state → API client: calls (evidence: `src/client/lib/session.tsx`)
- API client → Worker entry: HTTP requests
- Worker entry → Purchase workflow: registers (evidence: `src/worker/index.ts`)
- Worker entry → Authentication: registers (evidence: `src/worker/index.ts`)
- Worker entry → Settings: registers (evidence: `src/worker/index.ts`)
- Worker entry → Asset management: registers (evidence: `src/worker/index.ts`)
- Worker entry → Work orders: registers (evidence: `src/worker/index.ts`)
- Worker entry → Domain routes: registers (evidence: `src/worker/index.ts`)
- Purchase workflow → Session and permissions: uses access (evidence: `src/worker/routes/purchases.ts`)
- Purchase workflow → Database helpers: uses helpers (evidence: `src/worker/routes/purchases.ts`)
- Purchase workflow → Integration outbox: writes events (evidence: `src/worker/routes/purchases.ts`)
- Asset management → Session and permissions: uses access (evidence: `src/worker/routes/assets.ts`)
- Asset management → Database helpers: uses helpers (evidence: `src/worker/routes/assets.ts`)
- Asset management → Audit trail: records changes (evidence: `src/worker/routes/assets.ts`)
- Work orders → Database helpers: uses helpers (evidence: `src/worker/routes/workorders.ts`)
- Work orders → Audit trail: records changes (evidence: `src/worker/routes/workorders.ts`)
- Authentication → Session and permissions: creates sessions (evidence: `src/worker/routes/auth.ts`)
- Authentication → Audit trail: records events (evidence: `src/worker/routes/auth.ts`)
- Settings → Session and permissions: checks access (evidence: `src/worker/routes/settings.ts`)
- Settings → Audit trail: records changes (evidence: `src/worker/routes/settings.ts`)
- Session and permissions → D1 database: stores sessions (evidence: `src/worker/auth.ts`)
- Database helpers → D1 database: reads and writes
- Audit trail → D1 database: writes audit log (evidence: `src/worker/audit.ts`)
- Reports and exports → D1 database: queries reports
- Support chat → Realtime support room: realtime chat (evidence: `README.md`)
- Support chat → Optional attachments: stores attachments (evidence: `README.md`)
- Integration outbox → External systems: dispatches events (evidence: `README.md`)
