# brymahh/query_court architecture

> Architecture diagram of the GitHub repository brymahh/query_court, 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/brymahh/query_court
- Repository: https://github.com/brymahh/query_court

## Overview

The repository currently implements a small FastAPI foundation: it loads settings and serves a health endpoint, with a PostgreSQL connectivity helper. The README describes the broader Query-Court product—a streamed generator/critic SQL-review workflow with optional schema and sandbox checks, persistence, and tracing—but those components are not present in the supplied source tree. Those documented capabilities are shown as planned or unsampled components, using only supported paths. The workflow relationships beyond the health endpoint are README-level evidence, not inspected implementation.

Main entry points: [`src/app`](https://github.com/brymahh/query_court/tree/main/src/app) (Generator-critic workflow), [`src/app/main.py`](https://github.com/brymahh/query_court/blob/main/src/app/main.py) (FastAPI service), [`src/app/database.py`](https://github.com/brymahh/query_court/blob/main/src/app/database.py) (DB connectivity check), [`src/app/settings.py`](https://github.com/brymahh/query_court/blob/main/src/app/settings.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["API foundation"]
  node_api["FastAPI service<br/>[main.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_health["Health endpoint<br/>[main.py]"]
  node_db_check["DB connectivity check<br/>[database.py]"]
end

subgraph group_review["SQL review workflow"]
  node_workflow["Generator-critic workflow"]
  node_generator["SQL generator"]
  node_critic["SQL critic"]
  node_validators["Deterministic checks"]
end

subgraph group_context["Schema and execution"]
  node_schema_input["Schema context input"]
  node_ddl_parser["DDL schema parser"]
  node_sandbox["Isolated SQL sandbox"]
end

subgraph group_operations["History and observability"]
  node_postgres[("PostgreSQL history")]
  node_tracing["LangSmith tracing"]
end

node_user(("User"))
node_frontend["Next.js frontend"]

node_api -->|"loads config"| node_settings
node_api -->|"serves"| node_health
node_user -.->|"requests review"| node_api
node_frontend -.->|"streams events"| node_api
node_user -.->|"provides request"| node_workflow
node_workflow -.->|"requests SQL"| node_generator
node_workflow -.->|"requests critique"| node_critic
node_critic -.->|"runs checks"| node_validators
node_critic -.->|"uses context"| node_schema_input
node_schema_input -.->|"parses DDL"| node_ddl_parser
node_critic -.->|"optionally executes"| node_sandbox
node_workflow -.->|"stores history"| node_postgres
node_workflow -.->|"sends traces"| node_tracing
node_db_check -.->|"tests connection"| node_postgres

click node_api "https://github.com/brymahh/query_court/blob/main/src/app/main.py"
click node_settings "https://github.com/brymahh/query_court/blob/main/src/app/settings.py"
click node_health "https://github.com/brymahh/query_court/blob/main/src/app/main.py"
click node_db_check "https://github.com/brymahh/query_court/blob/main/src/app/database.py"
click node_workflow "https://github.com/brymahh/query_court/tree/main/src/app"
click node_generator "https://github.com/brymahh/query_court/tree/main/src/app"
click node_critic "https://github.com/brymahh/query_court/tree/main/src/app"
click node_validators "https://github.com/brymahh/query_court/tree/main/src/app"
click node_schema_input "https://github.com/brymahh/query_court/tree/main/src/app"
click node_ddl_parser "https://github.com/brymahh/query_court/tree/main/src/app"
click node_sandbox "https://github.com/brymahh/query_court/tree/main/src/app"

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_api,node_settings,node_health,node_db_check,node_user,node_frontend toneBlue
class node_workflow,node_generator,node_critic,node_validators toneAmber
class node_schema_input,node_ddl_parser,node_sandbox toneMint
class node_postgres,node_tracing toneRose
```

## Components

### API foundation

- [FastAPI service](https://github.com/brymahh/query_court/blob/main/src/app/main.py): `src/app/main.py`
- [Runtime settings](https://github.com/brymahh/query_court/blob/main/src/app/settings.py): `src/app/settings.py`
- [Health endpoint](https://github.com/brymahh/query_court/blob/main/src/app/main.py): `src/app/main.py`
- [DB connectivity check](https://github.com/brymahh/query_court/blob/main/src/app/database.py): `src/app/database.py`

### SQL review workflow

- [Generator-critic workflow](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`
- [SQL generator](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`
- [SQL critic](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`
- [Deterministic checks](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`

### Schema and execution

- [Schema context input](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`
- [DDL schema parser](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`
- [Isolated SQL sandbox](https://github.com/brymahh/query_court/tree/main/src/app): `src/app`

### History and observability

- **PostgreSQL history**
- **LangSmith tracing**

### Other components

- **User**
- **Next.js frontend**

## Connections

- FastAPI service → Runtime settings: loads config (evidence: `src/app/main.py`)
- FastAPI service → Health endpoint: serves (evidence: `src/app/main.py`)
- User → FastAPI service: requests review (evidence: `README.md`)
- Next.js frontend → FastAPI service: streams events (evidence: `README.md`)
- User → Generator-critic workflow: provides request (evidence: `README.md`)
- Generator-critic workflow → SQL generator: requests SQL (evidence: `README.md`)
- Generator-critic workflow → SQL critic: requests critique (evidence: `README.md`)
- SQL critic → Deterministic checks: runs checks (evidence: `README.md`)
- SQL critic → Schema context input: uses context (evidence: `README.md`)
- Schema context input → DDL schema parser: parses DDL (evidence: `README.md`)
- SQL critic → Isolated SQL sandbox: optionally executes (evidence: `README.md`)
- Generator-critic workflow → PostgreSQL history: stores history (evidence: `README.md`)
- Generator-critic workflow → LangSmith tracing: sends traces (evidence: `README.md`)
- DB connectivity check → PostgreSQL history: tests connection (evidence: `README.md`)
