# hmimotech/gsa architecture

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

- Interactive diagram: https://gitdiagram.com/hmimotech/gsa
- Repository: https://github.com/hmimotech/gsa

## Overview

GSA is a web platform for tracking work orders and associated purchases, linked to projects, contract periods, and ManageEngine ServiceDesk Plus. Users sign in, work with purchase dossiers through approval, quotation, delivery, and installation stages, and manage related files; administrators handle approvals and oversight. The frontend calls a FastAPI backend, whose route handlers use shared workflow, audit, notification, and SQLite layers. The README documents exports and Word attachment generation. Some subsystem links below rely on README descriptions or SOURCE INDEX references because their implementations were not excerpted.

Main entry points: [`backend/main.py`](https://github.com/hmimotech/gsa/blob/main/backend/main.py) (FastAPI application), [`backend/routes/contrats_route.py`](https://github.com/hmimotech/gsa/blob/main/backend/routes/contrats_route.py) (Contract periods), [`backend/database.py`](https://github.com/hmimotech/gsa/blob/main/backend/database.py) (SQLite database), [`backend/routes/auth_route.py`](https://github.com/hmimotech/gsa/blob/main/backend/routes/auth_route.py) (Login routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["Purchase workspace<br/>[app.js]"]
  node_project_ui["Project workspace<br/>[projects.js]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and access"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_login["Login routes<br/>[auth_route.py]"]
end

subgraph group_purchasing["Purchasing workflow"]
  node_dossiers["Purchase dossiers<br/>[dir_route.py]"]
  node_workflow["State transitions<br/>[workflow.py]"]
  node_files["File handling<br/>[files_route.py]"]
  node_quotes["Quote management<br/>[devis_route.py]"]
end

subgraph group_projects["Projects and contracts"]
  node_projects_route["Project management<br/>[projects_route.py]"]
  node_contracts["Contract periods<br/>[contrats_route.py]"]
  node_contract_rules["Contract helpers<br/>[contrats.py]"]
  node_documents["Word attachments<br/>[documents.py]"]
end

subgraph group_shared["Shared services"]
  node_sdp_proxy["ServiceDesk proxy<br/>[proxy_route.py]"]
  node_notifications["Notifications<br/>[notifications.py]"]
  node_audit["Audit logging<br/>[audit.py]"]
  node_database[("SQLite database<br/>[database.py]")]
  node_admin_routes["Oversight routes<br/>[stats_route.py]"]
end

node_user(("Staff and admins"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls"| node_api_client
node_project_ui -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_app
node_app -->|"registers"| node_login
node_app -->|"registers"| node_dossiers
node_app -->|"registers"| node_files
node_app -->|"registers"| node_quotes
node_app -->|"registers"| node_projects_route
node_app -->|"registers"| node_contracts
node_app -->|"registers"| node_sdp_proxy
node_login -->|"verifies identity"| node_auth
node_dossiers -->|"uses transitions"| node_workflow
node_quotes -->|"uses transitions"| node_workflow
node_contracts -->|"uses helpers"| node_contract_rules
node_contracts -->|"generates documents"| node_documents
node_dossiers -->|"fetches ticket data"| node_sdp_proxy
node_dossiers -->|"reads and writes"| node_database
node_quotes -->|"reads and writes"| node_database
node_files -->|"records file metadata"| node_database
node_projects_route -->|"reads and writes"| node_database
node_contracts -->|"reads and writes"| node_database
node_login -->|"reads accounts"| node_database
node_login -->|"records login events"| node_audit
node_quotes -->|"records actions"| node_audit
node_projects_route -->|"records actions"| node_audit
node_contracts -->|"records actions"| node_audit
node_admin_routes -->|"queries reporting data"| node_database
node_contracts -.->|"sends notifications"| node_notifications
node_files -.->|"sends notifications"| node_notifications

click node_frontend "https://github.com/hmimotech/gsa/blob/main/frontend/app.js"
click node_project_ui "https://github.com/hmimotech/gsa/blob/main/frontend/projects.js"
click node_api_client "https://github.com/hmimotech/gsa/blob/main/frontend/api.js"
click node_app "https://github.com/hmimotech/gsa/blob/main/backend/main.py"
click node_auth "https://github.com/hmimotech/gsa/blob/main/backend/auth.py"
click node_login "https://github.com/hmimotech/gsa/blob/main/backend/routes/auth_route.py"
click node_dossiers "https://github.com/hmimotech/gsa/blob/main/backend/routes/dir_route.py"
click node_workflow "https://github.com/hmimotech/gsa/blob/main/backend/workflow.py"
click node_files "https://github.com/hmimotech/gsa/blob/main/backend/routes/files_route.py"
click node_quotes "https://github.com/hmimotech/gsa/blob/main/backend/routes/devis_route.py"
click node_projects_route "https://github.com/hmimotech/gsa/blob/main/backend/routes/projects_route.py"
click node_contracts "https://github.com/hmimotech/gsa/blob/main/backend/routes/contrats_route.py"
click node_contract_rules "https://github.com/hmimotech/gsa/blob/main/backend/contrats.py"
click node_documents "https://github.com/hmimotech/gsa/blob/main/backend/documents.py"
click node_sdp_proxy "https://github.com/hmimotech/gsa/blob/main/backend/routes/proxy_route.py"
click node_notifications "https://github.com/hmimotech/gsa/blob/main/backend/notifications.py"
click node_audit "https://github.com/hmimotech/gsa/blob/main/backend/audit.py"
click node_database "https://github.com/hmimotech/gsa/blob/main/backend/database.py"
click node_admin_routes "https://github.com/hmimotech/gsa/blob/main/backend/routes/stats_route.py"

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_frontend,node_project_ui,node_api_client toneBlue
class node_app,node_auth,node_login toneAmber
class node_dossiers,node_workflow,node_files,node_quotes toneMint
class node_projects_route,node_contracts,node_contract_rules,node_documents toneRose
class node_sdp_proxy,node_notifications,node_audit,node_database,node_admin_routes,node_user toneIndigo
```

## Components

### Web client

- [Purchase workspace](https://github.com/hmimotech/gsa/blob/main/frontend/app.js): `frontend/app.js`
- [Project workspace](https://github.com/hmimotech/gsa/blob/main/frontend/projects.js): `frontend/projects.js`
- [API client](https://github.com/hmimotech/gsa/blob/main/frontend/api.js): `frontend/api.js`

### API and access

- [FastAPI application](https://github.com/hmimotech/gsa/blob/main/backend/main.py): `backend/main.py`
- [Authentication](https://github.com/hmimotech/gsa/blob/main/backend/auth.py): `backend/auth.py`
- [Login routes](https://github.com/hmimotech/gsa/blob/main/backend/routes/auth_route.py): `backend/routes/auth_route.py`

### Purchasing workflow

- [Purchase dossiers](https://github.com/hmimotech/gsa/blob/main/backend/routes/dir_route.py): `backend/routes/dir_route.py`
- [State transitions](https://github.com/hmimotech/gsa/blob/main/backend/workflow.py): `backend/workflow.py`
- [File handling](https://github.com/hmimotech/gsa/blob/main/backend/routes/files_route.py): `backend/routes/files_route.py`
- [Quote management](https://github.com/hmimotech/gsa/blob/main/backend/routes/devis_route.py): `backend/routes/devis_route.py`

### Projects and contracts

- [Project management](https://github.com/hmimotech/gsa/blob/main/backend/routes/projects_route.py): `backend/routes/projects_route.py`
- [Contract periods](https://github.com/hmimotech/gsa/blob/main/backend/routes/contrats_route.py): `backend/routes/contrats_route.py`
- [Contract helpers](https://github.com/hmimotech/gsa/blob/main/backend/contrats.py): `backend/contrats.py`
- [Word attachments](https://github.com/hmimotech/gsa/blob/main/backend/documents.py): `backend/documents.py`

### Shared services

- [ServiceDesk proxy](https://github.com/hmimotech/gsa/blob/main/backend/routes/proxy_route.py): `backend/routes/proxy_route.py`
- [Notifications](https://github.com/hmimotech/gsa/blob/main/backend/notifications.py): `backend/notifications.py`
- [Audit logging](https://github.com/hmimotech/gsa/blob/main/backend/audit.py): `backend/audit.py`
- [SQLite database](https://github.com/hmimotech/gsa/blob/main/backend/database.py): `backend/database.py`
- [Oversight routes](https://github.com/hmimotech/gsa/blob/main/backend/routes/stats_route.py): `backend/routes/stats_route.py`

### Other components

- **Staff and admins**

## Connections

- Staff and admins → Purchase workspace: uses (evidence: `README.md`)
- Purchase workspace → API client: calls (evidence: `README.md`)
- Project workspace → API client: calls (evidence: `README.md`)
- API client → FastAPI application: sends requests (evidence: `README.md`)
- FastAPI application → Login routes: registers (evidence: `backend/main.py`)
- FastAPI application → Purchase dossiers: registers (evidence: `backend/main.py`)
- FastAPI application → File handling: registers (evidence: `backend/main.py`)
- FastAPI application → Quote management: registers (evidence: `backend/main.py`)
- FastAPI application → Project management: registers (evidence: `backend/main.py`)
- FastAPI application → Contract periods: registers (evidence: `backend/main.py`)
- FastAPI application → ServiceDesk proxy: registers (evidence: `backend/main.py`)
- Login routes → Authentication: verifies identity (evidence: `backend/routes/auth_route.py`)
- Purchase dossiers → State transitions: uses transitions (evidence: `backend/routes/dir_route.py`)
- Quote management → State transitions: uses transitions (evidence: `backend/routes/devis_route.py`)
- Contract periods → Contract helpers: uses helpers (evidence: `backend/routes/contrats_route.py`)
- Contract periods → Word attachments: generates documents (evidence: `backend/routes/contrats_route.py`)
- Purchase dossiers → ServiceDesk proxy: fetches ticket data (evidence: `backend/routes/dir_route.py`)
- Purchase dossiers → SQLite database: reads and writes (evidence: `backend/routes/dir_route.py`)
- Quote management → SQLite database: reads and writes (evidence: `backend/routes/devis_route.py`)
- File handling → SQLite database: records file metadata (evidence: `backend/routes/files_route.py`)
- Project management → SQLite database: reads and writes (evidence: `backend/routes/projects_route.py`)
- Contract periods → SQLite database: reads and writes (evidence: `backend/routes/contrats_route.py`)
- Login routes → SQLite database: reads accounts (evidence: `backend/routes/auth_route.py`)
- Login routes → Audit logging: records login events (evidence: `backend/routes/auth_route.py`)
- Quote management → Audit logging: records actions (evidence: `backend/routes/devis_route.py`)
- Project management → Audit logging: records actions (evidence: `backend/routes/projects_route.py`)
- Contract periods → Audit logging: records actions (evidence: `backend/routes/contrats_route.py`)
- Oversight routes → SQLite database: queries reporting data (evidence: `backend/routes/stats_route.py`)
- Contract periods → Notifications: sends notifications
- File handling → Notifications: sends notifications (evidence: `backend/routes/files_route.py`)
