# brepublic/quorum architecture

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

- Interactive diagram: https://gitdiagram.com/brepublic/quorum
- Repository: https://github.com/brepublic/quorum

## Overview

Quorum is a self-hosted Model UN committee-management web application. Users enter through the browser UI and same-origin API; the server authenticates them, applies committee and proceedings rules, and persists changes in PostgreSQL. Its domain spans committee setup, live proceedings and voting, collaborative files, search, and storage administration. The optional Chair Local Agent connects through a separate server integration. The README documents the product workflow and capabilities; source excerpts and the SOURCE INDEX support the more specific server relationships shown. Unsampled subsystems are represented at their exact enclosing directories where details are limited.

Main entry points: [`server/src/http/app.ts`](https://github.com/brepublic/quorum/blob/master/server/src/http/app.ts) (HTTP API), [`server/src/modules/storage/file-service.ts`](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/file-service.ts) (File and upload services), [`server/src/modules/stage4/service.ts`](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage4/service.ts) (Committee setup), [`server/src/modules/stage3/service.ts`](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage3/service.ts) (Rules and operation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser client"]
  node_ui["Self-hosted UI"]
  node_api_client["API client<br/>[self-hosted-api.ts]"]
end

subgraph group_server["Server and identity"]
  node_http["HTTP API<br/>[app.ts]"]
  node_identity["Identity and sessions"]
  node_postgres[("PostgreSQL")]
  node_contracts["Shared contracts<br/>[domain.ts]"]
end

subgraph group_domain["Committee workflow"]
  node_committee["Committee setup<br/>[service.ts]"]
  node_rules["Rules and operation<br/>[service.ts]"]
  node_proceedings["Meetings and voting<br/>[service.ts]"]
  node_crises["Crisis management<br/>[crises.ts]"]
  node_search["Search"]
end

subgraph group_files["Files and storage"]
  node_delegate_files["Delegate file review<br/>[service.ts]"]
  node_file_storage["File and upload services<br/>[file-service.ts]"]
  node_storage["Storage providers<br/>[service.ts]"]
  node_s3["S3 configuration"]
  node_staging["Upload staging<br/>[staging.ts]"]
  node_cache["Storage cache"]
  node_operations["Archive and audit"]
end

subgraph group_agent["Local agent"]
  node_agent["Chair Local Agent"]
  node_agent_service["Agent coordination<br/>[service.ts]"]
  node_agent_events["Agent event stream"]
end

node_user(("Committee user"))

node_user -->|"uses"| node_ui
node_ui -->|"requests API"| node_api_client
node_api_client -->|"calls same-origin API"| node_http
node_http -->|"authenticates requests"| node_identity
node_http -->|"routes committee actions"| node_committee
node_http -->|"routes rule actions"| node_rules
node_http -->|"routes proceedings"| node_proceedings
node_http -->|"routes file actions"| node_delegate_files
node_http -->|"routes downloads"| node_file_storage
node_http -->|"routes event stream"| node_agent_events
node_agent_events -->|"streams events"| node_agent_service
node_agent -.->|"connects optionally"| node_agent_service
node_committee -.->|"persists committee data"| node_postgres
node_rules -.->|"stores rule state"| node_postgres
node_proceedings -.->|"records votes"| node_postgres
node_committee -->|"uses shared types"| node_contracts
node_rules -->|"closes crisis groups"| node_crises
node_proceedings -->|"reconciles crisis results"| node_crises
node_committee -->|"indexes workspace"| node_search
node_delegate_files -->|"lists and reviews files"| node_file_storage
node_file_storage -->|"uses storage services"| node_storage
node_file_storage -->|"uses upload staging"| node_staging
node_file_storage -->|"uses provider config"| node_s3
node_cache -->|"reads cache state"| node_postgres
node_operations -.->|"records operations"| node_postgres
node_agent_service -->|"checks manager access"| node_identity
node_http -->|"formats API responses"| node_contracts

click node_ui "https://github.com/brepublic/quorum/tree/master/src/pages/self-hosted"
click node_api_client "https://github.com/brepublic/quorum/blob/master/src/services/self-hosted-api.ts"
click node_http "https://github.com/brepublic/quorum/blob/master/server/src/http/app.ts"
click node_identity "https://github.com/brepublic/quorum/tree/master/server/src/modules/identity"
click node_contracts "https://github.com/brepublic/quorum/blob/master/packages/contracts/src/domain.ts"
click node_committee "https://github.com/brepublic/quorum/blob/master/server/src/modules/stage4/service.ts"
click node_rules "https://github.com/brepublic/quorum/blob/master/server/src/modules/stage3/service.ts"
click node_proceedings "https://github.com/brepublic/quorum/blob/master/server/src/modules/stage5/service.ts"
click node_crises "https://github.com/brepublic/quorum/blob/master/server/src/modules/stage5/crises.ts"
click node_search "https://github.com/brepublic/quorum/tree/master/server/src/modules/search"
click node_delegate_files "https://github.com/brepublic/quorum/blob/master/server/src/modules/delegate-files/service.ts"
click node_file_storage "https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/file-service.ts"
click node_storage "https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/service.ts"
click node_s3 "https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/s3-config-service.ts"
click node_staging "https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/staging.ts"
click node_cache "https://github.com/brepublic/quorum/blob/master/server/src/modules/operations/storage-cache-service.ts"
click node_operations "https://github.com/brepublic/quorum/tree/master/server/src/modules/operations"
click node_agent "https://github.com/brepublic/quorum/tree/master/packages/storage-agent/src"
click node_agent_service "https://github.com/brepublic/quorum/blob/master/server/src/modules/storage-agent/service.ts"
click node_agent_events "https://github.com/brepublic/quorum/blob/master/server/src/http/storage-agent-sse.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_ui,node_api_client,node_user toneBlue
class node_http,node_identity,node_postgres,node_contracts toneAmber
class node_committee,node_rules,node_proceedings,node_crises,node_search toneMint
class node_delegate_files,node_file_storage,node_storage,node_s3,node_staging,node_cache,node_operations toneRose
class node_agent,node_agent_service,node_agent_events toneIndigo
```

## Components

### Browser client

- [Self-hosted UI](https://github.com/brepublic/quorum/tree/master/src/pages/self-hosted): `src/pages/self-hosted`
- [API client](https://github.com/brepublic/quorum/blob/master/src/services/self-hosted-api.ts): `src/services/self-hosted-api.ts`

### Server and identity

- [HTTP API](https://github.com/brepublic/quorum/blob/master/server/src/http/app.ts): `server/src/http/app.ts`
- [Identity and sessions](https://github.com/brepublic/quorum/tree/master/server/src/modules/identity): `server/src/modules/identity`
- **PostgreSQL**
- [Shared contracts](https://github.com/brepublic/quorum/blob/master/packages/contracts/src/domain.ts): `packages/contracts/src/domain.ts`

### Committee workflow

- [Committee setup](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage4/service.ts): `server/src/modules/stage4/service.ts`
- [Rules and operation](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage3/service.ts): `server/src/modules/stage3/service.ts`
- [Meetings and voting](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage5/service.ts): `server/src/modules/stage5/service.ts`
- [Crisis management](https://github.com/brepublic/quorum/blob/master/server/src/modules/stage5/crises.ts): `server/src/modules/stage5/crises.ts`
- [Search](https://github.com/brepublic/quorum/tree/master/server/src/modules/search): `server/src/modules/search`

### Files and storage

- [Delegate file review](https://github.com/brepublic/quorum/blob/master/server/src/modules/delegate-files/service.ts): `server/src/modules/delegate-files/service.ts`
- [File and upload services](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/file-service.ts): `server/src/modules/storage/file-service.ts`
- [Storage providers](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/service.ts): `server/src/modules/storage/service.ts`
- [S3 configuration](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/s3-config-service.ts): `server/src/modules/storage/s3-config-service.ts`
- [Upload staging](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage/staging.ts): `server/src/modules/storage/staging.ts`
- [Storage cache](https://github.com/brepublic/quorum/blob/master/server/src/modules/operations/storage-cache-service.ts): `server/src/modules/operations/storage-cache-service.ts`
- [Archive and audit](https://github.com/brepublic/quorum/tree/master/server/src/modules/operations): `server/src/modules/operations`

### Local agent

- [Chair Local Agent](https://github.com/brepublic/quorum/tree/master/packages/storage-agent/src): `packages/storage-agent/src`
- [Agent coordination](https://github.com/brepublic/quorum/blob/master/server/src/modules/storage-agent/service.ts): `server/src/modules/storage-agent/service.ts`
- [Agent event stream](https://github.com/brepublic/quorum/blob/master/server/src/http/storage-agent-sse.ts): `server/src/http/storage-agent-sse.ts`

### Other components

- **Committee user**

## Connections

- Committee user → Self-hosted UI: uses (evidence: `README.md`)
- Self-hosted UI → API client: requests API (evidence: `src/pages/self-hosted/StorageAdminPanel.tsx`)
- API client → HTTP API: calls same-origin API (evidence: `README.md`)
- HTTP API → Identity and sessions: authenticates requests (evidence: `server/src/http/app.ts`)
- HTTP API → Committee setup: routes committee actions (evidence: `server/src/http/app.ts`)
- HTTP API → Rules and operation: routes rule actions (evidence: `server/src/http/app.ts`)
- HTTP API → Meetings and voting: routes proceedings (evidence: `server/src/http/app.ts`)
- HTTP API → Delegate file review: routes file actions (evidence: `server/src/http/app.ts`)
- HTTP API → File and upload services: routes downloads (evidence: `server/src/http/app.ts`)
- HTTP API → Agent event stream: routes event stream (evidence: `server/src/http/app.ts`)
- Agent event stream → Agent coordination: streams events (evidence: `server/src/http/storage-agent-sse.ts`)
- Chair Local Agent → Agent coordination: connects optionally
- Committee setup → PostgreSQL: persists committee data
- Rules and operation → PostgreSQL: stores rule state
- Meetings and voting → PostgreSQL: records votes
- Committee setup → Shared contracts: uses shared types (evidence: `server/src/modules/stage4/service.ts`)
- Rules and operation → Crisis management: closes crisis groups (evidence: `server/src/modules/stage3/service.ts`)
- Meetings and voting → Crisis management: reconciles crisis results (evidence: `server/src/modules/stage5/service.ts`)
- Committee setup → Search: indexes workspace (evidence: `server/src/modules/stage4/service.ts`)
- Delegate file review → File and upload services: lists and reviews files (evidence: `server/src/modules/delegate-files/service.ts`)
- File and upload services → Storage providers: uses storage services (evidence: `server/src/modules/storage/file-service.ts`)
- File and upload services → Upload staging: uses upload staging (evidence: `server/src/modules/storage/file-service.ts`)
- File and upload services → S3 configuration: uses provider config (evidence: `server/src/modules/storage/file-service.ts`)
- Storage cache → PostgreSQL: reads cache state (evidence: `server/src/modules/operations/storage-cache-service.ts`)
- Archive and audit → PostgreSQL: records operations
- Agent coordination → Identity and sessions: checks manager access (evidence: `server/src/modules/storage-agent/service.ts`)
- HTTP API → Shared contracts: formats API responses (evidence: `server/src/http/app.ts`)
