# cognicai/sequelspeak architecture

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

- Interactive diagram: https://gitdiagram.com/cognicai/sequelspeak
- Repository: https://github.com/cognicai/sequelspeak

## Overview

SequelSpeak is a schema-aware natural-language-to-SQL application, but the checked-in query path is currently an initialization boundary: the API validates a query, creates conversation state, and does not yet run the documented persona pipeline. The implemented user workflow also includes authenticated database connection setup and saved profiles. The README describes later SQL generation, validation, execution, explanation, clarification, retrieval, analytics, and feedback capabilities; these are shown as planned/documented stages, not verified runtime calls. Some subsystem wiring is documented or indexed rather than visible in excerpts.

Main entry points: [`backend/api/v1/query.py`](https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/query.py) (Query endpoint), [`frontend/src/components/ConnectionForm.tsx`](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/components/ConnectionForm.tsx) (Connection form), [`backend/main.py`](https://github.com/cognicai/sequelspeak/blob/main/backend/main.py) (FastAPI application), [`backend/services/db_connection_service.py`](https://github.com/cognicai/sequelspeak/blob/main/backend/services/db_connection_service.py) (Connection service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_app["Application shell<br/>[App.tsx]"]
  node_connection_form["Connection form<br/>[ConnectionForm.tsx]"]
  node_profile_selector["Profile selector"]
  node_profile_storage["Profile storage<br/>[profileStorage.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["Backend API"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth["JWT authentication<br/>[auth.py]"]
  node_query_api["Query endpoint<br/>[query.py]"]
  node_query_contract["Query contract<br/>[router.py]"]
  node_connection_api["Connection endpoint<br/>[connection.py]"]
  node_profiles_api["Profiles endpoint<br/>[profiles.py]"]
end

subgraph group_state["Conversation and profiles"]
  node_router_service["Router initialization<br/>[router_service.py]"]
  node_conversation_state["Conversation state"]
  node_profile_service["Profile service<br/>[profile_service.py]"]
  node_profile_db[("Internal profile database<br/>[db.py]")]
  node_credential_cache["Credential cache<br/>[profile_service.py]"]
end

subgraph group_connect["Database connectivity"]
  node_db_service["Connection service"]
  node_pool["Connection pool<br/>[connection_pool.py]"]
  node_circuit_breaker["Circuit breaker<br/>[circuit_breaker.py]"]
end

subgraph group_roadmap["Documented query pipeline"]
  node_schema_expert["Schema scoping"]
  node_context_retriever["Context retrieval"]
  node_sql_writer["SQL generation"]
  node_sql_guardian["SQL validation"]
  node_executor["Query execution"]
  node_explainer["Result explanation"]
  node_analytics_learning["Analytics and feedback"]
end

node_user(("User"))
node_target_db[("User PostgreSQL")]
node_redis[("Redis")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_connection_form
node_connection_form -->|"renders"| node_profile_selector
node_connection_form -->|"uses"| node_profile_storage
node_profile_storage -->|"calls"| node_api_client
node_connection_form -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"registers"| node_query_api
node_fastapi -->|"registers"| node_connection_api
node_fastapi -->|"registers"| node_profiles_api
node_query_api -->|"authenticates"| node_auth
node_query_api -->|"validates"| node_query_contract
node_query_api -->|"initializes"| node_router_service
node_query_api -->|"updates metadata"| node_conversation_state
node_router_service -->|"persists state"| node_conversation_state
node_conversation_state -->|"stores state"| node_redis
node_profiles_api -->|"delegates"| node_profile_service
node_profile_service -->|"reads and writes"| node_profile_db
node_profile_service -->|"caches credentials"| node_credential_cache
node_credential_cache -->|"encrypted cache"| node_redis
node_connection_api -->|"tests connection"| node_db_service
node_db_service -->|"gets pool"| node_pool
node_db_service -->|"guards test"| node_circuit_breaker
node_db_service -->|"connects"| node_target_db
node_query_api -.->|"planned dispatch"| node_schema_expert
node_query_api -.->|"planned dispatch"| node_context_retriever
node_schema_expert -.->|"provides schema"| node_sql_writer
node_context_retriever -.->|"provides context"| node_sql_writer
node_sql_writer -.->|"submits SQL"| node_sql_guardian
node_sql_guardian -.->|"approves SQL"| node_executor
node_executor -.->|"executes query"| node_target_db
node_executor -.->|"returns results"| node_explainer
node_executor -.->|"planned results and feedback"| node_analytics_learning
node_user -.->|"feedback"| node_analytics_learning

click node_app "https://github.com/cognicai/sequelspeak/blob/main/frontend/src/App.tsx"
click node_connection_form "https://github.com/cognicai/sequelspeak/blob/main/frontend/src/components/ConnectionForm.tsx"
click node_profile_selector "https://github.com/cognicai/sequelspeak/blob/main/frontend/src/components/ProfileSelector.tsx"
click node_profile_storage "https://github.com/cognicai/sequelspeak/blob/main/frontend/src/services/profileStorage.ts"
click node_api_client "https://github.com/cognicai/sequelspeak/blob/main/frontend/src/services/api/client.ts"
click node_fastapi "https://github.com/cognicai/sequelspeak/blob/main/backend/main.py"
click node_auth "https://github.com/cognicai/sequelspeak/blob/main/backend/utils/auth.py"
click node_query_api "https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/query.py"
click node_query_contract "https://github.com/cognicai/sequelspeak/blob/main/backend/schemas/router.py"
click node_connection_api "https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/connection.py"
click node_profiles_api "https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/profiles.py"
click node_router_service "https://github.com/cognicai/sequelspeak/blob/main/backend/services/router_service.py"
click node_conversation_state "https://github.com/cognicai/sequelspeak/blob/main/backend/services/conversation_state.py"
click node_profile_service "https://github.com/cognicai/sequelspeak/blob/main/backend/services/profile_service.py"
click node_profile_db "https://github.com/cognicai/sequelspeak/blob/main/backend/utils/db.py"
click node_credential_cache "https://github.com/cognicai/sequelspeak/blob/main/backend/services/profile_service.py"
click node_db_service "https://github.com/cognicai/sequelspeak/blob/main/backend/services/db_connection_service.py"
click node_pool "https://github.com/cognicai/sequelspeak/blob/main/backend/services/connection_pool.py"
click node_circuit_breaker "https://github.com/cognicai/sequelspeak/blob/main/backend/utils/circuit_breaker.py"
click node_schema_expert "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_context_retriever "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_sql_writer "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_sql_guardian "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_executor "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_explainer "https://github.com/cognicai/sequelspeak/tree/main/backend/services"
click node_analytics_learning "https://github.com/cognicai/sequelspeak/tree/main/backend/services"

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_app,node_connection_form,node_profile_selector,node_profile_storage,node_api_client,node_user toneBlue
class node_fastapi,node_auth,node_query_api,node_query_contract,node_connection_api,node_profiles_api,node_target_db,node_redis toneAmber
class node_router_service,node_conversation_state,node_profile_service,node_profile_db,node_credential_cache toneMint
class node_db_service,node_pool,node_circuit_breaker toneRose
class node_schema_expert,node_context_retriever,node_sql_writer,node_sql_guardian,node_executor,node_explainer,node_analytics_learning toneIndigo
```

## Components

### Web interface

- [Application shell](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Connection form](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/components/ConnectionForm.tsx): `frontend/src/components/ConnectionForm.tsx`
- [Profile selector](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/components/ProfileSelector.tsx): `frontend/src/components/ProfileSelector.tsx`
- [Profile storage](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/services/profileStorage.ts): `frontend/src/services/profileStorage.ts`
- [API client](https://github.com/cognicai/sequelspeak/blob/main/frontend/src/services/api/client.ts): `frontend/src/services/api/client.ts`

### Backend API

- [FastAPI application](https://github.com/cognicai/sequelspeak/blob/main/backend/main.py): `backend/main.py`
- [JWT authentication](https://github.com/cognicai/sequelspeak/blob/main/backend/utils/auth.py): `backend/utils/auth.py`
- [Query endpoint](https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/query.py): `backend/api/v1/query.py`
- [Query contract](https://github.com/cognicai/sequelspeak/blob/main/backend/schemas/router.py): `backend/schemas/router.py`
- [Connection endpoint](https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/connection.py): `backend/api/v1/connection.py`
- [Profiles endpoint](https://github.com/cognicai/sequelspeak/blob/main/backend/api/v1/profiles.py): `backend/api/v1/profiles.py`

### Conversation and profiles

- [Router initialization](https://github.com/cognicai/sequelspeak/blob/main/backend/services/router_service.py): `backend/services/router_service.py`
- [Conversation state](https://github.com/cognicai/sequelspeak/blob/main/backend/services/conversation_state.py): `backend/services/conversation_state.py`
- [Profile service](https://github.com/cognicai/sequelspeak/blob/main/backend/services/profile_service.py): `backend/services/profile_service.py`
- [Internal profile database](https://github.com/cognicai/sequelspeak/blob/main/backend/utils/db.py): `backend/utils/db.py`
- [Credential cache](https://github.com/cognicai/sequelspeak/blob/main/backend/services/profile_service.py): `backend/services/profile_service.py`

### Database connectivity

- [Connection service](https://github.com/cognicai/sequelspeak/blob/main/backend/services/db_connection_service.py): `backend/services/db_connection_service.py`
- [Connection pool](https://github.com/cognicai/sequelspeak/blob/main/backend/services/connection_pool.py): `backend/services/connection_pool.py`
- [Circuit breaker](https://github.com/cognicai/sequelspeak/blob/main/backend/utils/circuit_breaker.py): `backend/utils/circuit_breaker.py`

### Documented query pipeline

- [Schema scoping](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [Context retrieval](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [SQL generation](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [SQL validation](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [Query execution](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [Result explanation](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`
- [Analytics and feedback](https://github.com/cognicai/sequelspeak/tree/main/backend/services): `backend/services`

### Other components

- **User**
- **User PostgreSQL**
- **Redis**

## Connections

- User → Application shell: uses (evidence: `README.md`)
- Application shell → Connection form: renders (evidence: `frontend/src/App.tsx`)
- Connection form → Profile selector: renders (evidence: `frontend/src/components/ConnectionForm.tsx`)
- Connection form → Profile storage: uses (evidence: `frontend/src/components/ConnectionForm.tsx`)
- Profile storage → API client: calls (evidence: `frontend/src/services/profileStorage.ts`)
- Connection form → API client: calls (evidence: `frontend/src/components/ConnectionForm.tsx`)
- API client → FastAPI application: HTTP requests (evidence: `README.md`)
- FastAPI application → Query endpoint: registers (evidence: `backend/main.py`)
- FastAPI application → Connection endpoint: registers (evidence: `backend/main.py`)
- FastAPI application → Profiles endpoint: registers (evidence: `backend/main.py`)
- Query endpoint → JWT authentication: authenticates (evidence: `backend/api/v1/query.py`)
- Query endpoint → Query contract: validates (evidence: `backend/api/v1/query.py`)
- Query endpoint → Router initialization: initializes (evidence: `backend/api/v1/query.py`)
- Query endpoint → Conversation state: updates metadata (evidence: `backend/api/v1/query.py`)
- Router initialization → Conversation state: persists state (evidence: `backend/services/router_service.py`)
- Conversation state → Redis: stores state (evidence: `README.md`)
- Profiles endpoint → Profile service: delegates (evidence: `backend/api/v1/profiles.py`)
- Profile service → Internal profile database: reads and writes (evidence: `backend/services/profile_service.py`)
- Profile service → Credential cache: caches credentials (evidence: `backend/services/profile_service.py`)
- Credential cache → Redis: encrypted cache (evidence: `README.md`)
- Connection endpoint → Connection service: tests connection (evidence: `backend/api/v1/connection.py`)
- Connection service → Connection pool: gets pool (evidence: `backend/services/db_connection_service.py`)
- Connection service → Circuit breaker: guards test (evidence: `backend/services/db_connection_service.py`)
- Connection service → User PostgreSQL: connects (evidence: `backend/services/db_connection_service.py`)
- Query endpoint → Schema scoping: planned dispatch (evidence: `README.md`)
- Query endpoint → Context retrieval: planned dispatch (evidence: `README.md`)
- Schema scoping → SQL generation: provides schema (evidence: `README.md`)
- Context retrieval → SQL generation: provides context (evidence: `README.md`)
- SQL generation → SQL validation: submits SQL (evidence: `README.md`)
- SQL validation → Query execution: approves SQL (evidence: `README.md`)
- Query execution → User PostgreSQL: executes query (evidence: `README.md`)
- Query execution → Result explanation: returns results (evidence: `README.md`)
- Query execution → Analytics and feedback: planned results and feedback (evidence: `README.md`)
- User → Analytics and feedback: feedback (evidence: `README.md`)
