# praveen-goml/genaitask architecture

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

- Interactive diagram: https://gitdiagram.com/praveen-goml/genaitask
- Repository: https://github.com/praveen-goml/genaitask

## Overview

#### Purpose and entry points
JARVIS is a Python assistant backend combining retrieval-augmented generation (RAG), conversational memory, and guarded natural-language-to-SQL. It exposes an HTTP API, plus CLI and Streamlit interfaces.
- API application: `JARVIS/src/api/main.py`
- Interactive clients: `JARVIS/src/ui/cli.py`, `JARVIS/src/ui/streamlit_app.py`
- API route surface: `JARVIS/src/api/routes/chat.py`, `JARVIS/src/api/routes/sql.py`, `JARVIS/src/api/routes/health.py`

#### API and session boundary
The API layer validates request/response payloads, dispatches chat and SQL requests, and provides a health endpoint. Session state is separated from request routing, allowing chat continuity to be managed independently of the transport layer.
- Schemas: `JARVIS/src/api/schemas.py`
- Session handling: `JARVIS/src/api/session_store.py`
- Chat route: `JARVIS/src/api/routes/chat.py`

#### Agent orchestration
The core agent is the central control point for user interactions. It coordinates the LLM, RAG context, memory, and available tools, selecting or composing these capabilities for a response rather than embedding that logic in UI or route code.
- Agent: `JARVIS/src/core/agent.py`
- LLM integration boundary: `JARVIS/src/core/llm.py`
- Tool integration: `JARVIS/src/core/tools.py`

#### Retrieval-augmented knowledge flow
Documents under `data/documents` are ingested, chunked, embedded/indexed, and retrieved to ground responses. Retrieval is isolated from agent orchestration, while chunking and vector persistence are separate concerns.
- Ingestion entry point: `JARVIS/scripts/ingest.py`
- RAG pipeline: `JARVIS/src/core/rag.py`
- Chunking and vector storage: `JARVIS/src/core/chunking.py`, `JARVIS/src/core/vector_store.py`
- Source corpus: `JARVIS/data/documents`

#### Conversational memory
Conversation memory is a distinct core subsystem, likely used by the agent alongside retrieved documents. This separates transient/session-level chat context from the durable knowledge corpus and relational database.
- Memory component: `JARVIS/src/core/memory.py`
- Agent consumer: `JARVIS/src/core/agent.py`
- API session boundary: `JARVIS/src/api/session_store.py`

#### Relational data and NL-to-SQL safety pipeline
Natural-language SQL requests follow a dedicated pipeline: inspect available schema, generate SQL, validate/guard it, then execute against the database layer. This is a material safety boundary: SQL generation is not directly coupled to API routing or agent internals.
- Pipeline and generator: `JARVIS/src/nl2sql/pipeline.py`, `JARVIS/src/nl2sql/generator.py`
- Guard and schema inspection: `JARVIS/src/nl2sql/guard.py`, `JARVIS/src/nl2sql/schema_introspection.py`
- Database models/access: `JARVIS/src/db/database.py`, `JARVIS/src/db/models.py`

#### Runtime, initialization, and infrastructure
The repository is a Python service with dependency definitions and container orchestration. Database setup and seed data are explicit operational stages, separate from document ingestion.
- Dependencies: `JARVIS/requirements.txt`
- Container runtime composition: `JARVIS/docker-compose.yml`
- Database lifecycle scripts: `JARVIS/scripts/setup_db.py`, `JARVIS/scripts/seed_db.py`
- Environment configuration: `JARVIS/config/settings.py`, `JARVIS/.env.example`

Main entry points: [`JARVIS/src/api/routes/chat.py`](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/routes/chat.py) (API routes), [`JARVIS/src/core/agent.py`](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/agent.py) (Assistant agent), [`JARVIS/src/api/main.py`](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/main.py) (HTTP API), [`JARVIS/src/db/database.py`](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/db/database.py) (Relational database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_api_app["HTTP API<br/>FastAPI application<br/>[main.py]"]
  node_api_routes["API routes<br/>route handlers<br/>[chat.py]"]
  node_api_schemas["API schemas<br/>payload contracts<br/>[schemas.py]"]
  node_session_store["Session store<br/>session state<br/>[session_store.py]"]
  node_cli["CLI client<br/>interactive client<br/>[cli.py]"]
  node_streamlit["Streamlit client<br/>interactive client<br/>[streamlit_app.py]"]
end

subgraph group_assistant["Assistant Core"]
  node_agent{{"Assistant agent<br/>orchestrator<br/>[agent.py]"}}
  node_llm["LLM integration<br/>model boundary<br/>[llm.py]"]
  node_tools["Tool integration<br/>tool boundary<br/>[tools.py]"]
  node_memory["Conversation memory<br/>memory subsystem<br/>[memory.py]"]
end

subgraph group_retrieval["Knowledge Retrieval"]
  node_ingest["Document ingestion<br/>batch entry point<br/>[ingest.py]"]
  node_corpus["Document corpus<br/>knowledge source"]
  node_rag["RAG pipeline<br/>retrieval service<br/>[rag.py]"]
  node_chunking["Chunking<br/>document processing<br/>[chunking.py]"]
  node_vector_store[("Vector store<br/>embedding index<br/>[vector_store.py]")]
end

subgraph group_data["SQL Data Pipeline"]
  node_sql_pipeline{{"NL-to-SQL pipeline<br/>guarded SQL workflow<br/>[pipeline.py]"}}
  node_sql_generator["SQL generator<br/>NL-to-SQL<br/>[generator.py]"]
  node_sql_guard["SQL guard<br/>validation boundary<br/>[guard.py]"]
  node_schema_inspection["Schema inspection<br/>database metadata"]
  node_database[("Relational database<br/>database access and models<br/>[database.py]")]
end

subgraph group_operations["Operations"]
  node_db_lifecycle["Database lifecycle<br/>setup and seed scripts<br/>[setup_db.py]"]
  node_runtime["Container runtime<br/>service composition<br/>[docker-compose.yml]"]
end

node_cli -->|"uses"| node_api_app
node_streamlit -->|"uses"| node_api_app
node_api_app -->|"mounts"| node_api_routes
node_api_routes -->|"validates with"| node_api_schemas
node_api_routes -->|"manages sessions"| node_session_store
node_api_routes -->|"dispatches chat"| node_agent
node_api_routes -->|"dispatches SQL"| node_sql_pipeline
node_agent -->|"invokes"| node_llm
node_agent -->|"uses"| node_tools
node_agent -->|"reads and updates"| node_memory
node_agent -->|"retrieves context"| node_rag
node_corpus -->|"source documents"| node_ingest
node_ingest -->|"chunks"| node_chunking
node_chunking -->|"indexes"| node_vector_store
node_rag -->|"queries"| node_vector_store
node_sql_pipeline -->|"inspects schema"| node_schema_inspection
node_sql_pipeline -->|"generates SQL"| node_sql_generator
node_sql_generator -->|"submits for validation"| node_sql_guard
node_sql_guard -->|"permits execution"| node_database
node_schema_inspection -->|"reads metadata"| node_database
node_db_lifecycle -->|"sets up and seeds"| node_database
node_runtime -->|"runs"| node_api_app
node_runtime -->|"runs"| node_database

click node_api_app "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/main.py"
click node_api_routes "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/routes/chat.py"
click node_api_schemas "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/schemas.py"
click node_session_store "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/session_store.py"
click node_cli "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/ui/cli.py"
click node_streamlit "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/ui/streamlit_app.py"
click node_agent "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/agent.py"
click node_llm "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/llm.py"
click node_tools "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/tools.py"
click node_memory "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/memory.py"
click node_ingest "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/scripts/ingest.py"
click node_corpus "https://github.com/praveen-goml/genaitask/tree/feature/day1/JARVIS/data/documents"
click node_rag "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/rag.py"
click node_chunking "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/chunking.py"
click node_vector_store "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/vector_store.py"
click node_sql_pipeline "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/pipeline.py"
click node_sql_generator "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/generator.py"
click node_sql_guard "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/guard.py"
click node_schema_inspection "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/schema_introspection.py"
click node_database "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/db/database.py"
click node_db_lifecycle "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/scripts/setup_db.py"
click node_runtime "https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/docker-compose.yml"

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_app,node_api_routes,node_api_schemas,node_session_store,node_cli,node_streamlit toneBlue
class node_agent,node_llm,node_tools,node_memory toneAmber
class node_ingest,node_corpus,node_rag,node_chunking,node_vector_store toneMint
class node_sql_pipeline,node_sql_generator,node_sql_guard,node_schema_inspection,node_database toneRose
class node_db_lifecycle,node_runtime toneIndigo
```

## Components

### Interfaces

- [HTTP API](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/main.py): FastAPI application · `JARVIS/src/api/main.py`
- [API routes](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/routes/chat.py): route handlers · Chat, SQL, and health endpoints. · `JARVIS/src/api/routes/chat.py`
- [API schemas](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/schemas.py): payload contracts · `JARVIS/src/api/schemas.py`
- [Session store](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/api/session_store.py): session state · Keeps chat continuity separate from transport. · `JARVIS/src/api/session_store.py`
- [CLI client](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/ui/cli.py): interactive client · `JARVIS/src/ui/cli.py`
- [Streamlit client](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/ui/streamlit_app.py): interactive client · `JARVIS/src/ui/streamlit_app.py`

### Assistant Core

- [Assistant agent](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/agent.py): orchestrator · Composes LLM, retrieval, memory, and tools. · `JARVIS/src/core/agent.py`
- [LLM integration](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/llm.py): model boundary · `JARVIS/src/core/llm.py`
- [Tool integration](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/tools.py): tool boundary · `JARVIS/src/core/tools.py`
- [Conversation memory](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/memory.py): memory subsystem · `JARVIS/src/core/memory.py`

### Knowledge Retrieval

- [Document ingestion](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/scripts/ingest.py): batch entry point · `JARVIS/scripts/ingest.py`
- [Document corpus](https://github.com/praveen-goml/genaitask/tree/feature/day1/JARVIS/data/documents): knowledge source · `JARVIS/data/documents`
- [RAG pipeline](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/rag.py): retrieval service · `JARVIS/src/core/rag.py`
- [Chunking](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/chunking.py): document processing · `JARVIS/src/core/chunking.py`
- [Vector store](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/core/vector_store.py): embedding index · `JARVIS/src/core/vector_store.py`

### SQL Data Pipeline

- [NL-to-SQL pipeline](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/pipeline.py): guarded SQL workflow · Generates, validates, and executes SQL. · `JARVIS/src/nl2sql/pipeline.py`
- [SQL generator](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/generator.py): NL-to-SQL · `JARVIS/src/nl2sql/generator.py`
- [SQL guard](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/guard.py): validation boundary · `JARVIS/src/nl2sql/guard.py`
- [Schema inspection](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/nl2sql/schema_introspection.py): database metadata · `JARVIS/src/nl2sql/schema_introspection.py`
- [Relational database](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/src/db/database.py): database access and models · `JARVIS/src/db/database.py`

### Operations

- [Database lifecycle](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/scripts/setup_db.py): setup and seed scripts · `JARVIS/scripts/setup_db.py`
- [Container runtime](https://github.com/praveen-goml/genaitask/blob/feature/day1/JARVIS/docker-compose.yml): service composition · `JARVIS/docker-compose.yml`

## Connections

- CLI client → HTTP API: uses
- Streamlit client → HTTP API: uses
- HTTP API → API routes: mounts
- API routes → API schemas: validates with
- API routes → Session store: manages sessions
- API routes → Assistant agent: dispatches chat
- API routes → NL-to-SQL pipeline: dispatches SQL
- Assistant agent → LLM integration: invokes
- Assistant agent → Tool integration: uses
- Assistant agent → Conversation memory: reads and updates
- Assistant agent → RAG pipeline: retrieves context
- Document corpus → Document ingestion: source documents
- Document ingestion → Chunking: chunks
- Chunking → Vector store: indexes
- RAG pipeline → Vector store: queries
- NL-to-SQL pipeline → Schema inspection: inspects schema
- NL-to-SQL pipeline → SQL generator: generates SQL
- SQL generator → SQL guard: submits for validation
- SQL guard → Relational database: permits execution
- Schema inspection → Relational database: reads metadata
- Database lifecycle → Relational database: sets up and seeds
- Container runtime → HTTP API: runs
- Container runtime → Relational database: runs