# doyouhavetheguts/groundwork architecture

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

- Interactive diagram: https://gitdiagram.com/doyouhavetheguts/groundwork
- Repository: https://github.com/doyouhavetheguts/groundwork

## Overview

Groundwork is a capital-request intake and review application. A requester describes or imports a draft; the application structures it into Finance’s five sections, scores required items and findings, supports guided improvement rounds, then gates handoff and produces exports. The graph also preserves account/access control, image and exhibit capabilities, preview personas, and Finance escalation. The README documents the major workflow; some route-level wiring and unsampled module internals are not shown, so uncertain links are omitted or marked unverified.

Main entry points: [`app.py`](https://github.com/doyouhavetheguts/groundwork/blob/main/app.py) (HTTP Application), [`agents.py`](https://github.com/doyouhavetheguts/groundwork/blob/main/agents.py) (Draft Structuring), [`llm.py`](https://github.com/doyouhavetheguts/groundwork/blob/main/llm.py) (Model Client), [`images.py`](https://github.com/doyouhavetheguts/groundwork/blob/main/images.py) (Images and Diagrams)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Request Intake"]
  node_browser["Request UI<br/>[gw2.js]"]
  node_word_import["Word Import<br/>[docimport.py]"]
  node_image_tools["Images and Diagrams<br/>[images.py]"]
end

subgraph group_review["Draft Review"]
  node_drafting["Draft Structuring<br/>[agents.py]"]
  node_cleanup["Draft Cleanup<br/>[polish.py]"]
  node_scoring["Scoring and Gates<br/>[rubric.py]"]
  node_coaching["Guided Coaching<br/>[coach.py]"]
  node_model_client["Model Client<br/>[llm.py]"]
end

subgraph group_platform["Application Platform"]
  node_http["HTTP Application<br/>[app.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_identity["Identity and Roles<br/>[auth.py]"]
  node_database[("SQLite Store<br/>[store.py]")]
  node_preview["Edition Preview<br/>[preview.py]"]
end

subgraph group_handoff["Handoff"]
  node_export["Request Export<br/>[exporter.py]"]
  node_escalation["Finance Escalation<br/>[notify.py]"]
end

node_requester(("Requester"))
node_model_service{{"LLM Provider"}}
node_image_service{{"Image API"}}
node_reference_service{{"Wikimedia Commons"}}
node_finance_partner(("Finance Partner"))

node_requester -.->|"describes request"| node_browser
node_browser -.->|"submits request"| node_http
node_http -->|"checks access"| node_identity
node_http -->|"imports draft"| node_word_import
node_http -->|"structures draft"| node_drafting
node_drafting -->|"polishes text"| node_cleanup
node_drafting -->|"requests grading"| node_model_client
node_coaching -->|"generates questions"| node_model_client
node_drafting -->|"uses standard"| node_scoring
node_coaching -->|"re-scores draft"| node_scoring
node_http -->|"runs improvement"| node_coaching
node_http -->|"checks handoff gates"| node_scoring
node_model_client -->|"loads provider config"| node_settings
node_model_client -.->|"sends prompts"| node_model_service
node_http -->|"loads and saves"| node_database
node_identity -->|"reads accounts"| node_database
node_http -->|"serves image features"| node_image_tools
node_image_tools -.->|"requests examples"| node_image_service
node_image_tools -->|"searches references"| node_reference_service
node_http -->|"enters preview"| node_preview
node_preview -->|"seeds preview data"| node_database
node_http -->|"exports request"| node_export
node_http -->|"escalates after rounds"| node_escalation
node_escalation -->|"alerts partner"| node_finance_partner

click node_browser "https://github.com/doyouhavetheguts/groundwork/blob/main/static/gw2.js"
click node_http "https://github.com/doyouhavetheguts/groundwork/blob/main/app.py"
click node_word_import "https://github.com/doyouhavetheguts/groundwork/blob/main/docimport.py"
click node_drafting "https://github.com/doyouhavetheguts/groundwork/blob/main/agents.py"
click node_cleanup "https://github.com/doyouhavetheguts/groundwork/blob/main/polish.py"
click node_scoring "https://github.com/doyouhavetheguts/groundwork/blob/main/rubric.py"
click node_coaching "https://github.com/doyouhavetheguts/groundwork/blob/main/coach.py"
click node_model_client "https://github.com/doyouhavetheguts/groundwork/blob/main/llm.py"
click node_settings "https://github.com/doyouhavetheguts/groundwork/blob/main/config.py"
click node_identity "https://github.com/doyouhavetheguts/groundwork/blob/main/auth.py"
click node_database "https://github.com/doyouhavetheguts/groundwork/blob/main/store.py"
click node_image_tools "https://github.com/doyouhavetheguts/groundwork/blob/main/images.py"
click node_preview "https://github.com/doyouhavetheguts/groundwork/blob/main/preview.py"
click node_export "https://github.com/doyouhavetheguts/groundwork/blob/main/exporter.py"
click node_escalation "https://github.com/doyouhavetheguts/groundwork/blob/main/notify.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_browser,node_word_import,node_image_tools toneBlue
class node_drafting,node_cleanup,node_scoring,node_coaching,node_model_client toneAmber
class node_http,node_settings,node_identity,node_database,node_preview,node_requester,node_image_service toneMint
class node_export,node_escalation toneRose
class node_model_service,node_reference_service,node_finance_partner toneIndigo
```

## Components

### Request Intake

- [Request UI](https://github.com/doyouhavetheguts/groundwork/blob/main/static/gw2.js): `static/gw2.js`
- [Word Import](https://github.com/doyouhavetheguts/groundwork/blob/main/docimport.py): `docimport.py`
- [Images and Diagrams](https://github.com/doyouhavetheguts/groundwork/blob/main/images.py): `images.py`

### Draft Review

- [Draft Structuring](https://github.com/doyouhavetheguts/groundwork/blob/main/agents.py): `agents.py`
- [Draft Cleanup](https://github.com/doyouhavetheguts/groundwork/blob/main/polish.py): `polish.py`
- [Scoring and Gates](https://github.com/doyouhavetheguts/groundwork/blob/main/rubric.py): `rubric.py`
- [Guided Coaching](https://github.com/doyouhavetheguts/groundwork/blob/main/coach.py): `coach.py`
- [Model Client](https://github.com/doyouhavetheguts/groundwork/blob/main/llm.py): `llm.py`

### Application Platform

- [HTTP Application](https://github.com/doyouhavetheguts/groundwork/blob/main/app.py): `app.py`
- [Settings](https://github.com/doyouhavetheguts/groundwork/blob/main/config.py): `config.py`
- [Identity and Roles](https://github.com/doyouhavetheguts/groundwork/blob/main/auth.py): `auth.py`
- [SQLite Store](https://github.com/doyouhavetheguts/groundwork/blob/main/store.py): `store.py`
- [Edition Preview](https://github.com/doyouhavetheguts/groundwork/blob/main/preview.py): `preview.py`

### Handoff

- [Request Export](https://github.com/doyouhavetheguts/groundwork/blob/main/exporter.py): `exporter.py`
- [Finance Escalation](https://github.com/doyouhavetheguts/groundwork/blob/main/notify.py): `notify.py`

### Other components

- **Requester**
- **LLM Provider**
- **Image API**
- **Wikimedia Commons**
- **Finance Partner**

## Connections

- Requester → Request UI: describes request (evidence: `README.md`)
- Request UI → HTTP Application: submits request
- HTTP Application → Identity and Roles: checks access (evidence: `app.py`)
- HTTP Application → Word Import: imports draft (evidence: `README.md`)
- HTTP Application → Draft Structuring: structures draft (evidence: `README.md`)
- Draft Structuring → Draft Cleanup: polishes text (evidence: `agents.py`)
- Draft Structuring → Model Client: requests grading (evidence: `agents.py`)
- Guided Coaching → Model Client: generates questions (evidence: `coach.py`)
- Draft Structuring → Scoring and Gates: uses standard (evidence: `agents.py`)
- Guided Coaching → Scoring and Gates: re-scores draft (evidence: `README.md`)
- HTTP Application → Guided Coaching: runs improvement (evidence: `README.md`)
- HTTP Application → Scoring and Gates: checks handoff gates (evidence: `README.md`)
- Model Client → Settings: loads provider config (evidence: `llm.py`)
- Model Client → LLM Provider: sends prompts
- HTTP Application → SQLite Store: loads and saves (evidence: `app.py`)
- Identity and Roles → SQLite Store: reads accounts (evidence: `auth.py`)
- HTTP Application → Images and Diagrams: serves image features (evidence: `app.py`)
- Images and Diagrams → Image API: requests examples (evidence: `README.md`)
- Images and Diagrams → Wikimedia Commons: searches references
- HTTP Application → Edition Preview: enters preview (evidence: `app.py`)
- Edition Preview → SQLite Store: seeds preview data (evidence: `preview.py`)
- HTTP Application → Request Export: exports request (evidence: `README.md`)
- HTTP Application → Finance Escalation: escalates after rounds (evidence: `README.md`)
- Finance Escalation → Finance Partner: alerts partner (evidence: `README.md`)
