How cognicai/sequelspeak works
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: query.py Query endpoint · ConnectionForm.tsx Connection form · main.py FastAPI application · db_connection_service.py Connection service
Components 29
Web interface
- Application shell
frontend/src/App.tsx - Connection form
frontend/src/components/ConnectionForm.tsx - Profile selector
frontend/src/components/ProfileSelector.tsx - Profile storage
frontend/src/services/profileStorage.ts - API client
frontend/src/services/api/client.ts
Backend API
- FastAPI application
backend/main.py - JWT authentication
backend/utils/auth.py - Query endpoint
backend/api/v1/query.py - Query contract
backend/schemas/router.py - Connection endpoint
backend/api/v1/connection.py - Profiles endpoint
backend/api/v1/profiles.py
Conversation and profiles
- Router initialization
backend/services/router_service.py - Conversation state
backend/services/conversation_state.py - Profile service
backend/services/profile_service.py - Internal profile database
backend/utils/db.py - Credential cache
backend/services/profile_service.py
Database connectivity
- Connection service
backend/services/db_connection_service.py - Connection pool
backend/services/connection_pool.py - Circuit breaker
backend/utils/circuit_breaker.py
Documented query pipeline
- Schema scoping
backend/services - Context retrieval
backend/services - SQL generation
backend/services - SQL validation
backend/services - Query execution
backend/services - Result explanation
backend/services - Analytics and feedback
backend/services
Other components
- User
- User PostgreSQL
- Redis
Connections 34
- User → Application shell: uses
README.md - Application shell → Connection form: renders
frontend/src/App.tsx - Connection form → Profile selector: renders
frontend/src/components/ConnectionForm.tsx - Connection form → Profile storage: uses
frontend/src/components/ConnectionForm.tsx - Profile storage → API client: calls
frontend/src/services/profileStorage.ts - Connection form → API client: calls
frontend/src/components/ConnectionForm.tsx - API client → FastAPI application: HTTP requests
README.md - FastAPI application → Query endpoint: registers
backend/main.py - FastAPI application → Connection endpoint: registers
backend/main.py - FastAPI application → Profiles endpoint: registers
backend/main.py - Query endpoint → JWT authentication: authenticates
backend/api/v1/query.py - Query endpoint → Query contract: validates
backend/api/v1/query.py - Query endpoint → Router initialization: initializes
backend/api/v1/query.py - Query endpoint → Conversation state: updates metadata
backend/api/v1/query.py - Router initialization → Conversation state: persists state
backend/services/router_service.py - Conversation state → Redis: stores state
README.md - Profiles endpoint → Profile service: delegates
backend/api/v1/profiles.py - Profile service → Internal profile database: reads and writes
backend/services/profile_service.py - Profile service → Credential cache: caches credentials
backend/services/profile_service.py - Credential cache → Redis: encrypted cache
README.md - Connection endpoint → Connection service: tests connection
backend/api/v1/connection.py - Connection service → Connection pool: gets pool
backend/services/db_connection_service.py - Connection service → Circuit breaker: guards test
backend/services/db_connection_service.py - Connection service → User PostgreSQL: connects
backend/services/db_connection_service.py - Query endpoint → Schema scoping: planned dispatch
README.md - Query endpoint → Context retrieval: planned dispatch
README.md - Schema scoping → SQL generation: provides schema
README.md - Context retrieval → SQL generation: provides context
README.md - SQL generation → SQL validation: submits SQL
README.md - SQL validation → Query execution: approves SQL
README.md - Query execution → User PostgreSQL: executes query
README.md - Query execution → Result explanation: returns results
README.md - Query execution → Analytics and feedback: planned results and feedback
README.md - User → Analytics and feedback: feedback
README.md