# ujala100/setu-guide architecture

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

- Interactive diagram: https://gitdiagram.com/ujala100/setu-guide
- Repository: https://github.com/ujala100/setu-guide

## Overview

Setu Guide is a stage-aware relationship-guidance API. The main workflow accepts consented context and either a quick-action intent or message, applies request controls, then routes through intent handling, retrieval, response generation and safety checks to a structured reply. The README documents caching, rate limits, mock/fallback behavior and external-provider configuration. The graph reflects sampled code and documented capabilities; unsampled internals are represented only where the README or SOURCE INDEX supports them.

Main entry points: [`app/core/orchestrator.py`](https://github.com/ujala100/setu-guide/blob/dev/app/core/orchestrator.py) (Guide orchestrator), [`app/api/chat.py`](https://github.com/ujala100/setu-guide/blob/dev/app/api/chat.py) (Chat handler), [`app/api/main.py`](https://github.com/ujala100/setu-guide/blob/dev/app/api/main.py) (HTTP routes), [`app/core/pipeline.py`](https://github.com/ujala100/setu-guide/blob/dev/app/core/pipeline.py) (Generation pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and controls"]
  node_asgi["ASGI entry<br/>[main.py]"]
  node_routes["HTTP routes<br/>[main.py]"]
  node_chat["Chat handler<br/>[chat.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_limits["Rate limiter<br/>[ratelimit.py]"]
  node_cache[("Response cache<br/>[cache.py]")]
end

subgraph group_guidance["Guidance workflow"]
  node_schema["Guide schema<br/>[guide.py]"]
  node_orchestrator["Guide orchestrator<br/>[orchestrator.py]"]
  node_router["Intent router<br/>[router.py]"]
  node_pipeline["Generation pipeline<br/>[pipeline.py]"]
  node_responder["Template responder<br/>[responder.py]"]
  node_prompt_templates["Prompt templates"]
end

subgraph group_knowledge["Knowledge and safety"]
  node_retriever["Stage retrieval<br/>[retriever.py]"]
  node_knowledgebase["Knowledge chunks<br/>[kb_chunks.json]"]
  node_guard["Safety guard<br/>[guard.py]"]
end

subgraph group_providers["Generation and state"]
  node_provider["LLM providers<br/>[llm_provider.py]"]
end

node_client(("Express client"))
node_llm_service(("LLM service"))

node_client -->|"sends chat"| node_routes
node_asgi -->|"exposes app"| node_routes
node_routes -->|"dispatches chat"| node_chat
node_routes -->|"validates request"| node_schema
node_routes -->|"loads settings"| node_config
node_routes -->|"selects entry"| node_orchestrator
node_chat -->|"handles models"| node_schema
node_chat -->|"reads settings"| node_config
node_chat -->|"enforces limits"| node_limits
node_chat -->|"checks and stores"| node_cache
node_chat -->|"invokes entry"| node_orchestrator
node_orchestrator -->|"uses request models"| node_schema
node_orchestrator -->|"routes intent"| node_router
node_orchestrator -->|"retrieves context"| node_retriever
node_orchestrator -->|"checks safety"| node_guard
node_orchestrator -->|"generates reply"| node_pipeline
node_orchestrator -->|"uses fallback"| node_responder
node_pipeline -->|"routes intent"| node_router
node_pipeline -->|"requests generation"| node_provider
node_pipeline -->|"falls back"| node_responder
node_pipeline -->|"loads prompt"| node_prompt_templates
node_provider -->|"calls configured model"| node_llm_service
node_retriever -.->|"ranks chunks"| node_knowledgebase

click node_asgi "https://github.com/ujala100/setu-guide/blob/dev/app/main.py"
click node_routes "https://github.com/ujala100/setu-guide/blob/dev/app/api/main.py"
click node_chat "https://github.com/ujala100/setu-guide/blob/dev/app/api/chat.py"
click node_schema "https://github.com/ujala100/setu-guide/blob/dev/app/schemas/guide.py"
click node_config "https://github.com/ujala100/setu-guide/blob/dev/app/config.py"
click node_limits "https://github.com/ujala100/setu-guide/blob/dev/app/api/ratelimit.py"
click node_cache "https://github.com/ujala100/setu-guide/blob/dev/app/api/cache.py"
click node_orchestrator "https://github.com/ujala100/setu-guide/blob/dev/app/core/orchestrator.py"
click node_router "https://github.com/ujala100/setu-guide/blob/dev/app/core/router.py"
click node_retriever "https://github.com/ujala100/setu-guide/blob/dev/app/rag/retriever.py"
click node_knowledgebase "https://github.com/ujala100/setu-guide/blob/dev/app/rag/knowledge_base/kb_chunks.json"
click node_guard "https://github.com/ujala100/setu-guide/blob/dev/app/safety/guard.py"
click node_pipeline "https://github.com/ujala100/setu-guide/blob/dev/app/core/pipeline.py"
click node_responder "https://github.com/ujala100/setu-guide/blob/dev/app/core/responder.py"
click node_provider "https://github.com/ujala100/setu-guide/blob/dev/app/core/llm_provider.py"
click node_prompt_templates "https://github.com/ujala100/setu-guide/tree/dev/app/core/prompts"

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_asgi,node_routes,node_chat,node_config,node_limits,node_cache,node_client toneBlue
class node_schema,node_orchestrator,node_router,node_pipeline,node_responder,node_prompt_templates toneAmber
class node_retriever,node_knowledgebase,node_guard toneMint
class node_provider toneRose
class node_llm_service toneIndigo
```

## Components

### API and controls

- [ASGI entry](https://github.com/ujala100/setu-guide/blob/dev/app/main.py): `app/main.py`
- [HTTP routes](https://github.com/ujala100/setu-guide/blob/dev/app/api/main.py): `app/api/main.py`
- [Chat handler](https://github.com/ujala100/setu-guide/blob/dev/app/api/chat.py): `app/api/chat.py`
- [Runtime settings](https://github.com/ujala100/setu-guide/blob/dev/app/config.py): `app/config.py`
- [Rate limiter](https://github.com/ujala100/setu-guide/blob/dev/app/api/ratelimit.py): `app/api/ratelimit.py`
- [Response cache](https://github.com/ujala100/setu-guide/blob/dev/app/api/cache.py): `app/api/cache.py`

### Guidance workflow

- [Guide schema](https://github.com/ujala100/setu-guide/blob/dev/app/schemas/guide.py): `app/schemas/guide.py`
- [Guide orchestrator](https://github.com/ujala100/setu-guide/blob/dev/app/core/orchestrator.py): `app/core/orchestrator.py`
- [Intent router](https://github.com/ujala100/setu-guide/blob/dev/app/core/router.py): `app/core/router.py`
- [Generation pipeline](https://github.com/ujala100/setu-guide/blob/dev/app/core/pipeline.py): `app/core/pipeline.py`
- [Template responder](https://github.com/ujala100/setu-guide/blob/dev/app/core/responder.py): `app/core/responder.py`
- [Prompt templates](https://github.com/ujala100/setu-guide/tree/dev/app/core/prompts): `app/core/prompts`

### Knowledge and safety

- [Stage retrieval](https://github.com/ujala100/setu-guide/blob/dev/app/rag/retriever.py): `app/rag/retriever.py`
- [Knowledge chunks](https://github.com/ujala100/setu-guide/blob/dev/app/rag/knowledge_base/kb_chunks.json): `app/rag/knowledge_base/kb_chunks.json`
- [Safety guard](https://github.com/ujala100/setu-guide/blob/dev/app/safety/guard.py): `app/safety/guard.py`

### Generation and state

- [LLM providers](https://github.com/ujala100/setu-guide/blob/dev/app/core/llm_provider.py): `app/core/llm_provider.py`

### Other components

- **Express client**
- **LLM service**

## Connections

- Express client → HTTP routes: sends chat (evidence: `README.md`)
- ASGI entry → HTTP routes: exposes app (evidence: `app/main.py`)
- HTTP routes → Chat handler: dispatches chat (evidence: `app/api/main.py`)
- HTTP routes → Guide schema: validates request (evidence: `app/api/main.py`)
- HTTP routes → Runtime settings: loads settings (evidence: `app/api/main.py`)
- HTTP routes → Guide orchestrator: selects entry (evidence: `app/api/main.py`)
- Chat handler → Guide schema: handles models (evidence: `app/api/chat.py`)
- Chat handler → Runtime settings: reads settings (evidence: `app/api/chat.py`)
- Chat handler → Rate limiter: enforces limits (evidence: `app/api/chat.py`)
- Chat handler → Response cache: checks and stores (evidence: `app/api/chat.py`)
- Chat handler → Guide orchestrator: invokes entry (evidence: `README.md`)
- Guide orchestrator → Guide schema: uses request models (evidence: `app/core/orchestrator.py`)
- Guide orchestrator → Intent router: routes intent (evidence: `app/core/orchestrator.py`)
- Guide orchestrator → Stage retrieval: retrieves context (evidence: `app/core/orchestrator.py`)
- Guide orchestrator → Safety guard: checks safety (evidence: `app/core/orchestrator.py`)
- Guide orchestrator → Generation pipeline: generates reply (evidence: `app/core/orchestrator.py`)
- Guide orchestrator → Template responder: uses fallback (evidence: `app/core/orchestrator.py`)
- Generation pipeline → Intent router: routes intent (evidence: `app/core/pipeline.py`)
- Generation pipeline → LLM providers: requests generation (evidence: `app/core/pipeline.py`)
- Generation pipeline → Template responder: falls back (evidence: `app/core/pipeline.py`)
- Generation pipeline → Prompt templates: loads prompt (evidence: `app/core/pipeline.py`)
- LLM providers → LLM service: calls configured model (evidence: `app/core/llm_provider.py`)
- Stage retrieval → Knowledge chunks: ranks chunks
