# naureenfathima/blockseblock-ai-bootcamp architecture

> Architecture diagram of the GitHub repository naureenfathima/blockseblock-ai-bootcamp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naureenfathima/blockseblock-ai-bootcamp
- Repository: https://github.com/naureenfathima/blockseblock-ai-bootcamp

## Overview

This repository is a cumulative bootcamp project for building a domain-specific AI assistant, rather than a single standalone feature. Its principal workflow runs from a user request through chat or smart routing, optional session history and document retrieval, and an LLM response; agent actions, MCP tools, voice, and image analysis extend that workflow. The graph combines sampled endpoint wiring with README-documented capabilities; unsampled feature internals are represented only where the tree supports their paths.

Main entry points: [`week-4-launch/feature-11-production-design/solution/main.py`](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/week-4-launch/feature-11-production-design/solution/main.py) (Assistant API), [`shared/agent.py`](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/agent.py) (Agent loop), [`shared/ingestion.py`](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/ingestion.py) (Document ingestion), [`shared/providers/factory.py`](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/providers/factory.py) (Provider selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_ui["Web interface<br/>[app.js]"]
  node_api["Assistant API<br/>[main.py]"]
  node_chat["Chat and schemas<br/>[models.py]"]
end

subgraph group_knowledge["Knowledge and memory"]
  node_sessions[("Session history<br/>[session_store.py]")]
  node_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_documents[("Document store<br/>[document_store.py]")]
  node_vectors[("Vector search<br/>[vector_store.py]")]
  node_retrieval_memory[("Retrieval memory")]
end

subgraph group_intelligence["AI and actions"]
  node_router["Smart routing<br/>[router.py]"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_planner["Task planner<br/>[planner.py]"]
  node_tools["Local tools<br/>[tools.py]"]
  node_mcp_client["MCP client<br/>[mcp_client.py]"]
  node_mcp_server["Domain MCP tools"]
  node_task_store[("Agent task state<br/>[task_store.py]")]
  node_llm_client["LLM interface<br/>[llm_client.py]"]
  node_provider_factory["Provider selection<br/>[factory.py]"]
  node_providers["Model providers"]
  node_voice_vision["Voice and vision<br/>[llm_client.py]"]
end

subgraph group_operations["Operations"]
  node_ops["Observability and limits<br/>[middleware.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

node_user(("User"))
node_model_service{{"Model services"}}

node_user -->|"uses"| node_ui
node_ui -->|"sends requests"| node_api
node_api -->|"validates"| node_chat
node_api -->|"reads and writes"| node_sessions
node_api -->|"ingests uploads"| node_ingestion
node_ingestion -->|"stores documents"| node_documents
node_ingestion -->|"indexes chunks"| node_vectors
node_api -->|"searches"| node_vectors
node_api -->|"classifies queries"| node_router
node_router -->|"selects retrieval"| node_vectors
node_api -->|"logs retrieval"| node_retrieval_memory
node_api -->|"runs tasks"| node_agent
node_agent -->|"plans steps"| node_planner
node_agent -->|"calls tools"| node_tools
node_agent -.->|"uses remote tools"| node_mcp_client
node_mcp_client -.->|"dispatches tools"| node_mcp_server
node_api -->|"reads task status"| node_task_store
node_api -->|"requests completion"| node_llm_client
node_llm_client -->|"selects provider"| node_provider_factory
node_provider_factory -->|"creates provider"| node_providers
node_providers -->|"calls model"| node_model_service
node_api -->|"handles voice and images"| node_voice_vision
node_voice_vision -->|"selects modality provider"| node_provider_factory
node_api -->|"applies safeguards"| node_ops
node_api -->|"reports metrics"| node_metrics

click node_ui "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/ui/app.js"
click node_api "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/week-4-launch/feature-11-production-design/solution/main.py"
click node_chat "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/models.py"
click node_sessions "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/session_store.py"
click node_ingestion "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/ingestion.py"
click node_documents "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/document_store.py"
click node_vectors "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/vector_store.py"
click node_router "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/router.py"
click node_retrieval_memory "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/retrieval_memory.py"
click node_agent "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/agent.py"
click node_planner "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/planner.py"
click node_tools "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/tools.py"
click node_mcp_client "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/mcp_client.py"
click node_mcp_server "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/domain_mcp_server.py"
click node_task_store "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/task_store.py"
click node_llm_client "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/llm_client.py"
click node_provider_factory "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/providers/factory.py"
click node_providers "https://github.com/naureenfathima/blockseblock-ai-bootcamp/tree/main/shared/providers"
click node_voice_vision "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/llm_client.py"
click node_ops "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/middleware.py"
click node_metrics "https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/metrics.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_ui,node_api,node_chat,node_user toneBlue
class node_sessions,node_ingestion,node_documents,node_vectors,node_retrieval_memory toneAmber
class node_router,node_agent,node_planner,node_tools,node_mcp_client,node_mcp_server,node_task_store,node_llm_client,node_provider_factory,node_providers,node_voice_vision toneMint
class node_ops,node_metrics toneRose
class node_model_service toneIndigo
```

## Components

### User experience

- [Web interface](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/ui/app.js): `ui/app.js`
- [Assistant API](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/week-4-launch/feature-11-production-design/solution/main.py): `week-4-launch/feature-11-production-design/solution/main.py`
- [Chat and schemas](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/models.py): `shared/models.py`

### Knowledge and memory

- [Session history](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/session_store.py): `shared/session_store.py`
- [Document ingestion](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/ingestion.py): `shared/ingestion.py`
- [Document store](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/document_store.py): `shared/document_store.py`
- [Vector search](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/vector_store.py): `shared/vector_store.py`
- [Retrieval memory](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/retrieval_memory.py): `shared/retrieval_memory.py`

### AI and actions

- [Smart routing](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/router.py): `shared/router.py`
- [Agent loop](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/agent.py): `shared/agent.py`
- [Task planner](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/planner.py): `shared/planner.py`
- [Local tools](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/tools.py): `shared/tools.py`
- [MCP client](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/mcp_client.py): `shared/mcp_client.py`
- [Domain MCP tools](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/domain_mcp_server.py): `shared/domain_mcp_server.py`
- [Agent task state](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/task_store.py): `shared/task_store.py`
- [LLM interface](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/llm_client.py): `shared/llm_client.py`
- [Provider selection](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/providers/factory.py): `shared/providers/factory.py`
- [Model providers](https://github.com/naureenfathima/blockseblock-ai-bootcamp/tree/main/shared/providers): `shared/providers`
- [Voice and vision](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/llm_client.py): `shared/llm_client.py`

### Operations

- [Observability and limits](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/middleware.py): `shared/middleware.py`
- [Metrics](https://github.com/naureenfathima/blockseblock-ai-bootcamp/blob/main/shared/metrics.py): `shared/metrics.py`

### Other components

- **User**
- **Model services**

## Connections

- User → Web interface: uses
- Web interface → Assistant API: sends requests
- Assistant API → Chat and schemas: validates
- Assistant API → Session history: reads and writes
- Assistant API → Document ingestion: ingests uploads
- Document ingestion → Document store: stores documents
- Document ingestion → Vector search: indexes chunks
- Assistant API → Vector search: searches
- Assistant API → Smart routing: classifies queries
- Smart routing → Vector search: selects retrieval
- Assistant API → Retrieval memory: logs retrieval
- Assistant API → Agent loop: runs tasks
- Agent loop → Task planner: plans steps
- Agent loop → Local tools: calls tools
- Agent loop → MCP client: uses remote tools
- MCP client → Domain MCP tools: dispatches tools
- Assistant API → Agent task state: reads task status
- Assistant API → LLM interface: requests completion
- LLM interface → Provider selection: selects provider
- Provider selection → Model providers: creates provider
- Model providers → Model services: calls model
- Assistant API → Voice and vision: handles voice and images
- Voice and vision → Provider selection: selects modality provider
- Assistant API → Observability and limits: applies safeguards
- Assistant API → Metrics: reports metrics