# musawaghu/firmflow architecture

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

- Interactive diagram: https://gitdiagram.com/musawaghu/firmflow
- Repository: https://github.com/musawaghu/firmflow

## Overview

FIRM FLOW turns firm onboarding documents and shared AEC guidance into approved, traceable learning for employees. Admins upload and review manuals, confirm firm-over-baseline overrides, configure modules, and monitor progress; employees complete prioritized modules, take a critical-content final check, or ask a directory-grounded assistant. The main implementation is the React frontend and FastAPI backend, with Supabase for auth and data and Claude for AI tasks. Some service internals were not sampled; documented capabilities are included, with uncertain connections omitted.

Main entry points: [`backend/app/main.py`](https://github.com/musawaghu/firmflow/blob/master/backend/app/main.py) (FastAPI application), [`frontend/src/App.tsx`](https://github.com/musawaghu/firmflow/blob/master/frontend/src/App.tsx) (React application), [`backend/app/routers/manuals.py`](https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/manuals.py) (Manual management), [`frontend/src/lib/api.ts`](https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/api.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_web["React application<br/>[App.tsx]"]
  node_authui["Sign-in and roles<br/>[auth.tsx]"]
  node_adminui["Admin workspace"]
  node_employeeui["Employee workspace"]
  node_apiclient["Typed API client<br/>[api.ts]"]
end

subgraph group_backend["API and services"]
  node_api["FastAPI application<br/>[main.py]"]
  node_account["Account and access<br/>[auth.py]"]
end

subgraph group_content["Content lifecycle"]
  node_manualroutes["Manual management<br/>[manuals.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_processing["Manual enhancement<br/>[processing.py]"]
  node_grounding["Grounding checks<br/>[grounding.py]"]
  node_overrides["Baseline overrides<br/>[overrides.py]"]
  node_contentservice["Firm and baseline content<br/>[content.py]"]
end

subgraph group_learning["Employee learning"]
  node_modules["Module management<br/>[modules.py]"]
  node_progress["Learning progress<br/>[progress.py]"]
  node_quiz["Final check<br/>[quiz.py]"]
  node_assistant["Question assistant<br/>[assistant.py]"]
  node_directory["Firm directory<br/>[directory.py]"]
end

subgraph group_platform["External platform"]
  node_store[("Database and storage<br/>[db.py]")]
  node_supabaseauth["Supabase Auth<br/>[supabase.ts]"]
  node_claude["Claude API"]
  node_supabase[("Supabase platform")]
end

node_employee(("Employee"))
node_admin(("Firm admin"))

node_employee -->|"uses"| node_web
node_admin -->|"uses"| node_web
node_web -->|"provides auth"| node_authui
node_web -->|"routes admins"| node_adminui
node_web -->|"routes employees"| node_employeeui
node_authui -->|"signs in"| node_supabaseauth
node_authui -->|"loads profile"| node_apiclient
node_adminui -->|"requests data"| node_apiclient
node_employeeui -.->|"requests data"| node_apiclient
node_apiclient -->|"calls REST"| node_api
node_api -->|"mounts routes"| node_account
node_api -->|"mounts routes"| node_manualroutes
node_api -->|"mounts routes"| node_modules
node_api -->|"mounts routes"| node_quiz
node_manualroutes -->|"parses uploads"| node_parser
node_manualroutes -.->|"starts processing"| node_processing
node_manualroutes -->|"manages proposals"| node_overrides
node_processing -.->|"checks grounding"| node_grounding
node_processing -.->|"enhances content"| node_claude
node_overrides -.->|"informs content"| node_contentservice
node_modules -->|"serves modules"| node_contentservice
node_modules -->|"checks passages"| node_grounding
node_quiz -->|"selects critical passages"| node_contentservice
node_quiz -->|"tracks attempts"| node_progress
node_assistant -->|"looks up contacts"| node_directory
node_assistant -.->|"answers questions"| node_claude
node_api -->|"uses repository"| node_store
node_store -->|"reads and writes"| node_supabase
node_supabaseauth -->|"authenticates"| node_supabase

click node_web "https://github.com/musawaghu/firmflow/blob/master/frontend/src/App.tsx"
click node_authui "https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/auth.tsx"
click node_adminui "https://github.com/musawaghu/firmflow/tree/master/frontend/src/pages/admin"
click node_employeeui "https://github.com/musawaghu/firmflow/tree/master/frontend/src/pages/employee"
click node_apiclient "https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/api.ts"
click node_api "https://github.com/musawaghu/firmflow/blob/master/backend/app/main.py"
click node_account "https://github.com/musawaghu/firmflow/blob/master/backend/app/auth.py"
click node_manualroutes "https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/manuals.py"
click node_parser "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/parser.py"
click node_processing "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/processing.py"
click node_grounding "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/grounding.py"
click node_overrides "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/overrides.py"
click node_contentservice "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/content.py"
click node_modules "https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/modules.py"
click node_progress "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/progress.py"
click node_quiz "https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/quiz.py"
click node_assistant "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/assistant.py"
click node_directory "https://github.com/musawaghu/firmflow/blob/master/backend/app/services/directory.py"
click node_store "https://github.com/musawaghu/firmflow/blob/master/backend/app/db.py"
click node_supabaseauth "https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/supabase.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_web,node_authui,node_adminui,node_employeeui,node_apiclient toneBlue
class node_api,node_account toneAmber
class node_manualroutes,node_parser,node_processing,node_grounding,node_overrides,node_contentservice toneMint
class node_modules,node_progress,node_quiz,node_assistant,node_directory toneRose
class node_store,node_supabaseauth,node_claude,node_supabase,node_employee,node_admin toneIndigo
```

## Components

### Web application

- [React application](https://github.com/musawaghu/firmflow/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Sign-in and roles](https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/auth.tsx): `frontend/src/lib/auth.tsx`
- [Admin workspace](https://github.com/musawaghu/firmflow/tree/master/frontend/src/pages/admin): `frontend/src/pages/admin`
- [Employee workspace](https://github.com/musawaghu/firmflow/tree/master/frontend/src/pages/employee): `frontend/src/pages/employee`
- [Typed API client](https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and services

- [FastAPI application](https://github.com/musawaghu/firmflow/blob/master/backend/app/main.py): `backend/app/main.py`
- [Account and access](https://github.com/musawaghu/firmflow/blob/master/backend/app/auth.py): `backend/app/auth.py`

### Content lifecycle

- [Manual management](https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/manuals.py): `backend/app/routers/manuals.py`
- [Document parser](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/parser.py): `backend/app/services/parser.py`
- [Manual enhancement](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/processing.py): `backend/app/services/processing.py`
- [Grounding checks](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/grounding.py): `backend/app/services/grounding.py`
- [Baseline overrides](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/overrides.py): `backend/app/services/overrides.py`
- [Firm and baseline content](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/content.py): `backend/app/services/content.py`

### Employee learning

- [Module management](https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/modules.py): `backend/app/routers/modules.py`
- [Learning progress](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/progress.py): `backend/app/services/progress.py`
- [Final check](https://github.com/musawaghu/firmflow/blob/master/backend/app/routers/quiz.py): `backend/app/routers/quiz.py`
- [Question assistant](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/assistant.py): `backend/app/services/assistant.py`
- [Firm directory](https://github.com/musawaghu/firmflow/blob/master/backend/app/services/directory.py): `backend/app/services/directory.py`

### External platform

- [Database and storage](https://github.com/musawaghu/firmflow/blob/master/backend/app/db.py): `backend/app/db.py`
- [Supabase Auth](https://github.com/musawaghu/firmflow/blob/master/frontend/src/lib/supabase.ts): `frontend/src/lib/supabase.ts`
- **Claude API**
- **Supabase platform**

### Other components

- **Employee**
- **Firm admin**

## Connections

- Employee → React application: uses (evidence: `README.md`)
- Firm admin → React application: uses (evidence: `README.md`)
- React application → Sign-in and roles: provides auth (evidence: `frontend/src/main.tsx`)
- React application → Admin workspace: routes admins (evidence: `frontend/src/App.tsx`)
- React application → Employee workspace: routes employees (evidence: `frontend/src/App.tsx`)
- Sign-in and roles → Supabase Auth: signs in (evidence: `frontend/src/lib/auth.tsx`)
- Sign-in and roles → Typed API client: loads profile (evidence: `frontend/src/lib/auth.tsx`)
- Admin workspace → Typed API client: requests data (evidence: `frontend/src/pages/admin/AdminLayout.tsx`)
- Employee workspace → Typed API client: requests data (evidence: `frontend/src/pages/employee/FinalCheck.tsx`)
- Typed API client → FastAPI application: calls REST (evidence: `README.md`)
- FastAPI application → Account and access: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Manual management: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Module management: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Final check: mounts routes (evidence: `backend/app/main.py`)
- Manual management → Document parser: parses uploads (evidence: `backend/app/routers/manuals.py`)
- Manual management → Manual enhancement: starts processing (evidence: `backend/app/routers/manuals.py`)
- Manual management → Baseline overrides: manages proposals (evidence: `backend/app/routers/manuals.py`)
- Manual enhancement → Grounding checks: checks grounding
- Manual enhancement → Claude API: enhances content (evidence: `README.md`)
- Baseline overrides → Firm and baseline content: informs content
- Module management → Firm and baseline content: serves modules (evidence: `backend/app/routers/modules.py`)
- Module management → Grounding checks: checks passages (evidence: `backend/app/routers/modules.py`)
- Final check → Firm and baseline content: selects critical passages (evidence: `backend/app/routers/quiz.py`)
- Final check → Learning progress: tracks attempts (evidence: `backend/app/routers/quiz.py`)
- Question assistant → Firm directory: looks up contacts (evidence: `README.md`)
- Question assistant → Claude API: answers questions (evidence: `README.md`)
- FastAPI application → Database and storage: uses repository (evidence: `backend/app/db.py`)
- Database and storage → Supabase platform: reads and writes (evidence: `README.md`)
- Supabase Auth → Supabase platform: authenticates (evidence: `README.md`)