# colingoonth/risk-management architecture

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

- Interactive diagram: https://gitdiagram.com/colingoonth/risk-management
- Repository: https://github.com/colingoonth/risk-management

## Overview

Risk Management is an offline-first, single-user app for a fraternity risk chair to manage event staffing and member discipline. The main workflow is to maintain a roster and term, create events, preview or make fair shift assignments, then handle swaps and strikes; the app also supports term archiving and GroupMe operations. The README describes a React-to-FastAPI-to-services-to-repositories-to-SQLite layering. Some routers and services were not sampled, so their internal call relationships are not detailed here.

Main entry points: [`src/risk/services`](https://github.com/colingoonth/risk-management/tree/main/src/risk/services) (Business Services), [`src/risk/api/app.py`](https://github.com/colingoonth/risk-management/blob/main/src/risk/api/app.py) (HTTP API), [`web/src/App.tsx`](https://github.com/colingoonth/risk-management/blob/main/web/src/App.tsx) (Web App), [`web/src/pages`](https://github.com/colingoonth/risk-management/tree/main/web/src/pages) (Management Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interfaces"]
  node_webapp["Web App<br/>[App.tsx]"]
  node_pages["Management Pages"]
  node_api_client["Typed API Client<br/>[api.ts]"]
  node_cli["Command Line<br/>[main.py]"]
  node_desktop["Desktop Launcher<br/>[__main__.py]"]
end

subgraph group_backend["Application Backend"]
  node_api["HTTP API<br/>[app.py]"]
  node_ingest_router["Roster Ingest Route<br/>[ingest.py]"]
  node_services["Business Services"]
end

subgraph group_domain["Risk Workflows"]
  node_ingest["Roster and Strike Ingest<br/>[ingest.py]"]
  node_staffing["Fair Shift Assignment<br/>[assignment.py]"]
  node_eligibility["Eligibility and Availability<br/>[eligibility.py]"]
  node_fairness["Assignment Fairness<br/>[fairness.py]"]
  node_policy["Pledge and House Policy<br/>[policy.py]"]
  node_discipline["Strike Tracking<br/>[strike_state.py]"]
  node_swaps["Shift Swaps<br/>[swaps.py]"]
  node_groupme["GroupMe Operations<br/>[groupme.py]"]
end

subgraph group_storage["Local Data"]
  node_repos["SQL Repositories"]
  node_db_layer["SQLite Access and Schema<br/>[connection.py]"]
  node_sqlite[("Local SQLite Database")]
end

node_chair(("Risk Chair"))

node_chair -->|"uses"| node_webapp
node_chair -->|"uses"| node_cli
node_webapp -->|"routes to"| node_pages
node_pages -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_api
node_api -->|"registers routes"| node_ingest_router
node_ingest_router -->|"calls"| node_ingest
node_api -->|"uses business rules"| node_services
node_cli -->|"runs ingest"| node_ingest
node_services -->|"uses"| node_repos
node_repos -->|"executes SQL"| node_db_layer
node_db_layer -->|"reads and writes"| node_sqlite
node_services -->|"includes"| node_staffing
node_services -->|"includes"| node_eligibility
node_services -->|"includes"| node_fairness
node_services -->|"includes"| node_policy
node_services -->|"includes"| node_discipline
node_services -->|"includes"| node_swaps
node_services -.->|"includes"| node_groupme
node_desktop -->|"starts"| node_api

click node_webapp "https://github.com/colingoonth/risk-management/blob/main/web/src/App.tsx"
click node_pages "https://github.com/colingoonth/risk-management/tree/main/web/src/pages"
click node_api_client "https://github.com/colingoonth/risk-management/blob/main/web/src/lib/api.ts"
click node_cli "https://github.com/colingoonth/risk-management/blob/main/src/risk/cli/main.py"
click node_desktop "https://github.com/colingoonth/risk-management/blob/main/src/risk/desktop/__main__.py"
click node_api "https://github.com/colingoonth/risk-management/blob/main/src/risk/api/app.py"
click node_ingest_router "https://github.com/colingoonth/risk-management/blob/main/src/risk/api/routers/ingest.py"
click node_services "https://github.com/colingoonth/risk-management/tree/main/src/risk/services"
click node_ingest "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/ingest.py"
click node_staffing "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/assignment.py"
click node_eligibility "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/eligibility.py"
click node_fairness "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/fairness.py"
click node_policy "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/policy.py"
click node_discipline "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/strike_state.py"
click node_swaps "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/swaps.py"
click node_groupme "https://github.com/colingoonth/risk-management/blob/main/src/risk/services/groupme.py"
click node_repos "https://github.com/colingoonth/risk-management/tree/main/src/risk/repos"
click node_db_layer "https://github.com/colingoonth/risk-management/blob/main/src/risk/db/connection.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_webapp,node_pages,node_api_client,node_cli,node_desktop toneBlue
class node_api,node_ingest_router,node_services toneAmber
class node_ingest,node_staffing,node_eligibility,node_fairness,node_policy,node_discipline,node_swaps,node_groupme toneMint
class node_repos,node_db_layer,node_sqlite toneRose
class node_chair toneIndigo
```

## Components

### User Interfaces

- [Web App](https://github.com/colingoonth/risk-management/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Management Pages](https://github.com/colingoonth/risk-management/tree/main/web/src/pages): `web/src/pages`
- [Typed API Client](https://github.com/colingoonth/risk-management/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`
- [Command Line](https://github.com/colingoonth/risk-management/blob/main/src/risk/cli/main.py): `src/risk/cli/main.py`
- [Desktop Launcher](https://github.com/colingoonth/risk-management/blob/main/src/risk/desktop/__main__.py): `src/risk/desktop/__main__.py`

### Application Backend

- [HTTP API](https://github.com/colingoonth/risk-management/blob/main/src/risk/api/app.py): `src/risk/api/app.py`
- [Roster Ingest Route](https://github.com/colingoonth/risk-management/blob/main/src/risk/api/routers/ingest.py): `src/risk/api/routers/ingest.py`
- [Business Services](https://github.com/colingoonth/risk-management/tree/main/src/risk/services): `src/risk/services`

### Risk Workflows

- [Roster and Strike Ingest](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/ingest.py): `src/risk/services/ingest.py`
- [Fair Shift Assignment](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/assignment.py): `src/risk/services/assignment.py`
- [Eligibility and Availability](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/eligibility.py): `src/risk/services/eligibility.py`
- [Assignment Fairness](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/fairness.py): `src/risk/services/fairness.py`
- [Pledge and House Policy](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/policy.py): `src/risk/services/policy.py`
- [Strike Tracking](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/strike_state.py): `src/risk/services/strike_state.py`
- [Shift Swaps](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/swaps.py): `src/risk/services/swaps.py`
- [GroupMe Operations](https://github.com/colingoonth/risk-management/blob/main/src/risk/services/groupme.py): `src/risk/services/groupme.py`

### Local Data

- [SQL Repositories](https://github.com/colingoonth/risk-management/tree/main/src/risk/repos): `src/risk/repos`
- [SQLite Access and Schema](https://github.com/colingoonth/risk-management/blob/main/src/risk/db/connection.py): `src/risk/db/connection.py`
- **Local SQLite Database**

### Other components

- **Risk Chair**

## Connections

- Risk Chair → Web App: uses (evidence: `README.md`)
- Risk Chair → Command Line: uses (evidence: `README.md`)
- Web App → Management Pages: routes to (evidence: `web/src/App.tsx`)
- Management Pages → Typed API Client: requests data (evidence: `web/src/pages/Ops.tsx`)
- Typed API Client → HTTP API: HTTP requests (evidence: `web/src/lib/api.ts`)
- HTTP API → Roster Ingest Route: registers routes (evidence: `src/risk/api/app.py`)
- Roster Ingest Route → Roster and Strike Ingest: calls (evidence: `src/risk/api/routers/ingest.py`)
- HTTP API → Business Services: uses business rules (evidence: `README.md`)
- Command Line → Roster and Strike Ingest: runs ingest
- Business Services → SQL Repositories: uses (evidence: `README.md`)
- SQL Repositories → SQLite Access and Schema: executes SQL (evidence: `README.md`)
- SQLite Access and Schema → Local SQLite Database: reads and writes (evidence: `README.md`)
- Business Services → Fair Shift Assignment: includes (evidence: `README.md`)
- Business Services → Eligibility and Availability: includes (evidence: `README.md`)
- Business Services → Assignment Fairness: includes (evidence: `README.md`)
- Business Services → Pledge and House Policy: includes (evidence: `README.md`)
- Business Services → Strike Tracking: includes (evidence: `README.md`)
- Business Services → Shift Swaps: includes (evidence: `README.md`)
- Business Services → GroupMe Operations: includes
- Desktop Launcher → HTTP API: starts (evidence: `src/risk/desktop/__main__.py`)
