Add architecture diagrams to README

Three Mermaid diagrams styled for beautiful-mermaid (tokyo-night): system overview (flowchart), data model (ER diagram), and expense approval flow (sequence diagram). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-14 10:57:26 +07:00
parent f2ca147eca
commit 722bd6c1c2
1 changed files with 98 additions and 0 deletions
@@ -33,6 +33,104 @@ A self-hosted, multi-company budget and project tracking tool built for internal

 ---

+## Architecture
+
+Diagrams use [Mermaid](https://mermaid.js.org/) and are designed to render cleanly through [beautiful-mermaid](https://github.com/lukilabs/beautiful-mermaid) (tokyo-night theme).
+
+### System Overview
+
+```mermaid
+%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#7aa2f7','lineColor':'#3d59a1','background':'#1a1b26'}}}%%
+flowchart LR
+    U[User Browser] -->|HTTPS| N[nginx reverse proxy]
+    N -->|127.0.0.1:3000| A[SvelteKit Node app]
+    A --> DB[(PostgreSQL)]
+    A -.optional.-> O[OIDC Provider]
+    subgraph Proxmox VM
+        N
+        A
+        DB
+    end
+```
+
+### Data Model
+
+```mermaid
+%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#7aa2f7','lineColor':'#3d59a1','background':'#1a1b26'}}}%%
+erDiagram
+    users ||--o{ sessions : has
+    users ||--o{ company_members : "belongs to"
+    companies ||--o{ company_members : has
+    companies ||--o{ projects : contains
+    companies ||--o{ categories : defines
+    companies ||--o{ tags : defines
+    companies ||--o{ budget_allocations : tracks
+    companies ||--o{ company_log : audits
+    projects ||--o{ expenses : contains
+    projects ||--o{ budget_allocations : receives
+    categories ||--o{ expenses : classifies
+    expenses ||--o{ expense_tags : has
+    tags ||--o{ expense_tags : tagged
+    users ||--o{ expenses : "submits / approves"
+
+    users {
+        text id PK
+        text email UK
+        text password_hash
+        text oidc_subject
+        bool is_system_admin
+        timestamp disabled_at
+    }
+    companies {
+        uuid id PK
+        text name
+        numeric total_budget
+        text currency
+        timestamp deleted_at
+    }
+    company_members {
+        uuid id PK
+        text user_id FK
+        uuid company_id FK
+        enum role "admin|manager|user|viewer"
+    }
+    projects {
+        uuid id PK
+        uuid company_id FK
+        numeric allocated_budget
+    }
+    expenses {
+        uuid id PK
+        uuid project_id FK
+        numeric amount
+        enum status "pending|approved|rejected"
+    }
+```
+
+### Expense Approval Flow
+
+```mermaid
+%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#7aa2f7','lineColor':'#3d59a1','background':'#1a1b26'}}}%%
+sequenceDiagram
+    actor U as User
+    actor M as Manager
+    participant A as SvelteKit
+    participant DB as PostgreSQL
+    participant L as Audit Log
+
+    U->>A: POST /projects/:id/expenses/new
+    A->>DB: INSERT expense (status=pending)
+    A->>L: log expense_submitted
+    A-->>U: 302 redirect
+    Note over M: Reviews pending queue
+    M->>A: POST /expenses/:id approve
+    A->>DB: UPDATE status=approved
+    A->>L: log expense_approved
+    A-->>M: success
+```
+
+---
+
 ## Prerequisites

 - Node.js 20 or later