# fightandsurvive/talon architecture

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

- Interactive diagram: https://gitdiagram.com/fightandsurvive/talon
- Repository: https://github.com/fightandsurvive/talon

## Overview

Talon accepts GUMP case data, queues it for serial per-operator processing, transforms it into FAMIS blocks, and submits it through GLink. Users can review errors and edits in the web interface; administrators manage operators and credentials. PostgreSQL stores queue state, operator mappings, and audit records. The README documents a workstation agent and AD-based access; the agent-to-server interaction is not visible in the sampled source, so that link is marked unverified.

Main entry points: [`src/talon/api/routes/submissions.py`](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/submissions.py) (Submission API), [`src/talon/workflow/worker.py`](https://github.com/fightandsurvive/talon/blob/main/src/talon/workflow/worker.py) (Queue worker), [`src/talon/famis/gump_parser.py`](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/gump_parser.py) (GUMP parser), [`src/talon/db/repository.py`](https://github.com/fightandsurvive/talon/blob/main/src/talon/db/repository.py) (Submission repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Submission and Review"]
  node_agent["Workstation agent<br/>[talon_agent.py]"]
  node_web["Web interface<br/>[routes.py]"]
  node_submissions["Submission API<br/>[submissions.py]"]
  node_review["Review API<br/>[review.py]"]
  node_admin["Admin API<br/>[admin.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_processing["Queue Processing"]
  node_worker["Queue worker<br/>[worker.py]"]
  node_workflow["FAMIS workflow<br/>[famis_workflow.py]"]
  node_glink["GLink session<br/>[session.py]"]
end

subgraph group_famis["FAMIS Data Handling"]
  node_parser["GUMP parser<br/>[gump_parser.py]"]
  node_adjustments["Field adjustments<br/>[adjustments.py]"]
  node_overrides["Field overrides<br/>[field_overrides.py]"]
  node_loader["Block loader<br/>[block_loader.py]"]
  node_blocks["FAMIS blocks<br/>[blocks.py]"]
end

subgraph group_platform["Application and Access"]
  node_app["Application startup<br/>[main.py]"]
  node_deps["API dependencies<br/>[deps.py]"]
  node_middleware["Auth middleware<br/>[middleware.py]"]
  node_ad["AD group checks<br/>[ad.py]"]
  node_crypto["Credential crypto<br/>[crypto.py]"]
  node_config["Settings<br/>[config.py]"]
end

subgraph group_persistence["Persistence"]
  node_engine["Database engine<br/>[engine.py]"]
  node_models["Database models<br/>[models.py]"]
  node_repository["Submission repository<br/>[repository.py]"]
end

node_user(("Talon user"))
node_famis_system(("NJ FAMIS"))

node_user -->|"uses"| node_web
node_user -->|"submits cases"| node_submissions
node_agent -.->|"submits cases"| node_submissions
node_app -->|"registers routes"| node_web
node_app -->|"registers routes"| node_submissions
node_app -->|"registers routes"| node_review
node_app -->|"registers routes"| node_admin
node_submissions -->|"parses GUMP"| node_parser
node_submissions -->|"creates submissions"| node_repository
node_review -->|"records edits"| node_repository
node_review -->|"uses schemas"| node_schemas
node_web -->|"parses review data"| node_parser
node_web -->|"reads submissions"| node_repository
node_admin -->|"manages operators"| node_models
node_submissions -->|"uses schemas"| node_schemas
node_worker -->|"claims and updates"| node_repository
node_worker -->|"parses queued data"| node_parser
node_worker -->|"adjusts case data"| node_adjustments
node_worker -->|"runs workflow"| node_workflow
node_worker -->|"opens session"| node_glink
node_workflow -->|"transmits fields"| node_glink
node_workflow -->|"applies rules"| node_adjustments
node_glink -->|"emulates terminal"| node_famis_system
node_parser -->|"instantiates blocks"| node_loader
node_parser -->|"fills collections"| node_blocks
node_loader -->|"builds definitions"| node_blocks
node_adjustments -->|"updates fields"| node_blocks
node_adjustments -->|"uses overrides"| node_overrides
node_deps -->|"identifies users"| node_middleware
node_deps -->|"checks groups"| node_ad
node_deps -->|"gets database session"| node_engine
node_middleware -->|"uses group checks"| node_ad
node_ad -->|"reads settings"| node_config
node_crypto -->|"reads settings"| node_config
node_engine -->|"loads database URL"| node_config
node_models -->|"uses ORM base"| node_engine
node_repository -->|"queries records"| node_models

click node_agent "https://github.com/fightandsurvive/talon/blob/main/workstation/talon_agent/talon_agent.py"
click node_web "https://github.com/fightandsurvive/talon/blob/main/src/talon/web/routes.py"
click node_submissions "https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/submissions.py"
click node_review "https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/review.py"
click node_admin "https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/admin.py"
click node_schemas "https://github.com/fightandsurvive/talon/blob/main/src/talon/api/schemas.py"
click node_worker "https://github.com/fightandsurvive/talon/blob/main/src/talon/workflow/worker.py"
click node_workflow "https://github.com/fightandsurvive/talon/blob/main/src/talon/workflow/famis_workflow.py"
click node_parser "https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/gump_parser.py"
click node_adjustments "https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/adjustments.py"
click node_overrides "https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/field_overrides.py"
click node_loader "https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/block_loader.py"
click node_blocks "https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/blocks.py"
click node_glink "https://github.com/fightandsurvive/talon/blob/main/src/talon/glink/session.py"
click node_app "https://github.com/fightandsurvive/talon/blob/main/src/talon/main.py"
click node_deps "https://github.com/fightandsurvive/talon/blob/main/src/talon/api/deps.py"
click node_middleware "https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/middleware.py"
click node_ad "https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/ad.py"
click node_crypto "https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/crypto.py"
click node_config "https://github.com/fightandsurvive/talon/blob/main/src/talon/config.py"
click node_engine "https://github.com/fightandsurvive/talon/blob/main/src/talon/db/engine.py"
click node_models "https://github.com/fightandsurvive/talon/blob/main/src/talon/db/models.py"
click node_repository "https://github.com/fightandsurvive/talon/blob/main/src/talon/db/repository.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_agent,node_web,node_submissions,node_review,node_admin,node_schemas,node_user toneBlue
class node_worker,node_workflow,node_glink toneAmber
class node_parser,node_adjustments,node_overrides,node_loader,node_blocks toneMint
class node_app,node_deps,node_middleware,node_ad,node_crypto,node_config toneRose
class node_engine,node_models,node_repository,node_famis_system toneIndigo
```

## Components

### Submission and Review

- [Workstation agent](https://github.com/fightandsurvive/talon/blob/main/workstation/talon_agent/talon_agent.py): `workstation/talon_agent/talon_agent.py`
- [Web interface](https://github.com/fightandsurvive/talon/blob/main/src/talon/web/routes.py): `src/talon/web/routes.py`
- [Submission API](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/submissions.py): `src/talon/api/routes/submissions.py`
- [Review API](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/review.py): `src/talon/api/routes/review.py`
- [Admin API](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/routes/admin.py): `src/talon/api/routes/admin.py`
- [API schemas](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/schemas.py): `src/talon/api/schemas.py`

### Queue Processing

- [Queue worker](https://github.com/fightandsurvive/talon/blob/main/src/talon/workflow/worker.py): `src/talon/workflow/worker.py`
- [FAMIS workflow](https://github.com/fightandsurvive/talon/blob/main/src/talon/workflow/famis_workflow.py): `src/talon/workflow/famis_workflow.py`
- [GLink session](https://github.com/fightandsurvive/talon/blob/main/src/talon/glink/session.py): `src/talon/glink/session.py`

### FAMIS Data Handling

- [GUMP parser](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/gump_parser.py): `src/talon/famis/gump_parser.py`
- [Field adjustments](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/adjustments.py): `src/talon/famis/adjustments.py`
- [Field overrides](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/field_overrides.py): `src/talon/famis/field_overrides.py`
- [Block loader](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/block_loader.py): `src/talon/famis/block_loader.py`
- [FAMIS blocks](https://github.com/fightandsurvive/talon/blob/main/src/talon/famis/blocks.py): `src/talon/famis/blocks.py`

### Application and Access

- [Application startup](https://github.com/fightandsurvive/talon/blob/main/src/talon/main.py): `src/talon/main.py`
- [API dependencies](https://github.com/fightandsurvive/talon/blob/main/src/talon/api/deps.py): `src/talon/api/deps.py`
- [Auth middleware](https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/middleware.py): `src/talon/auth/middleware.py`
- [AD group checks](https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/ad.py): `src/talon/auth/ad.py`
- [Credential crypto](https://github.com/fightandsurvive/talon/blob/main/src/talon/auth/crypto.py): `src/talon/auth/crypto.py`
- [Settings](https://github.com/fightandsurvive/talon/blob/main/src/talon/config.py): `src/talon/config.py`

### Persistence

- [Database engine](https://github.com/fightandsurvive/talon/blob/main/src/talon/db/engine.py): `src/talon/db/engine.py`
- [Database models](https://github.com/fightandsurvive/talon/blob/main/src/talon/db/models.py): `src/talon/db/models.py`
- [Submission repository](https://github.com/fightandsurvive/talon/blob/main/src/talon/db/repository.py): `src/talon/db/repository.py`

### Other components

- **Talon user**
- **NJ FAMIS**

## Connections

- Talon user → Web interface: uses (evidence: `src/talon/web/routes.py`)
- Talon user → Submission API: submits cases (evidence: `README.md`)
- Workstation agent → Submission API: submits cases
- Application startup → Web interface: registers routes (evidence: `src/talon/main.py`)
- Application startup → Submission API: registers routes (evidence: `src/talon/main.py`)
- Application startup → Review API: registers routes (evidence: `src/talon/main.py`)
- Application startup → Admin API: registers routes (evidence: `src/talon/main.py`)
- Submission API → GUMP parser: parses GUMP (evidence: `src/talon/api/routes/submissions.py`)
- Submission API → Submission repository: creates submissions (evidence: `src/talon/api/routes/submissions.py`)
- Review API → Submission repository: records edits (evidence: `src/talon/api/routes/review.py`)
- Review API → API schemas: uses schemas (evidence: `src/talon/api/routes/review.py`)
- Web interface → GUMP parser: parses review data (evidence: `src/talon/web/routes.py`)
- Web interface → Submission repository: reads submissions (evidence: `src/talon/web/routes.py`)
- Admin API → Database models: manages operators (evidence: `src/talon/api/routes/admin.py`)
- Submission API → API schemas: uses schemas (evidence: `src/talon/api/routes/submissions.py`)
- Queue worker → Submission repository: claims and updates (evidence: `src/talon/workflow/worker.py`)
- Queue worker → GUMP parser: parses queued data (evidence: `src/talon/workflow/worker.py`)
- Queue worker → Field adjustments: adjusts case data (evidence: `src/talon/workflow/worker.py`)
- Queue worker → FAMIS workflow: runs workflow (evidence: `src/talon/workflow/worker.py`)
- Queue worker → GLink session: opens session (evidence: `src/talon/workflow/worker.py`)
- FAMIS workflow → GLink session: transmits fields (evidence: `src/talon/workflow/famis_workflow.py`)
- FAMIS workflow → Field adjustments: applies rules (evidence: `src/talon/workflow/famis_workflow.py`)
- GLink session → NJ FAMIS: emulates terminal (evidence: `README.md`)
- GUMP parser → Block loader: instantiates blocks (evidence: `src/talon/famis/gump_parser.py`)
- GUMP parser → FAMIS blocks: fills collections (evidence: `src/talon/famis/gump_parser.py`)
- Block loader → FAMIS blocks: builds definitions (evidence: `src/talon/famis/block_loader.py`)
- Field adjustments → FAMIS blocks: updates fields (evidence: `src/talon/famis/adjustments.py`)
- Field adjustments → Field overrides: uses overrides (evidence: `src/talon/famis/adjustments.py`)
- API dependencies → Auth middleware: identifies users (evidence: `src/talon/api/deps.py`)
- API dependencies → AD group checks: checks groups (evidence: `src/talon/api/deps.py`)
- API dependencies → Database engine: gets database session (evidence: `src/talon/api/deps.py`)
- Auth middleware → AD group checks: uses group checks (evidence: `src/talon/auth/middleware.py`)
- AD group checks → Settings: reads settings (evidence: `src/talon/auth/ad.py`)
- Credential crypto → Settings: reads settings (evidence: `src/talon/auth/crypto.py`)
- Database engine → Settings: loads database URL (evidence: `src/talon/db/engine.py`)
- Database models → Database engine: uses ORM base (evidence: `src/talon/db/models.py`)
- Submission repository → Database models: queries records (evidence: `src/talon/db/repository.py`)
