# kapil31jangid/civora architecture

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

- Interactive diagram: https://gitdiagram.com/kapil31jangid/civora
- Repository: https://github.com/kapil31jangid/civora

## Overview

Civora turns a citizen’s urban-problem description into safe, measurable SDG 11 guidance through a browser chat, server-side routing, domain prompts, and Gemini. The main path runs from the chat UI through the API and chat route to response generation; optional conversation persistence adds browser-scoped history via Supabase or an in-memory store. The README documents specialist modes, one-time action formats, and stateless Arena requests. Some links to unsampled modules rely on SOURCE INDEX references or README statements rather than inspected implementations.

Main entry points: [`client/src/App.tsx`](https://github.com/kapil31jangid/civora/blob/main/client/src/App.tsx) (Chat app), [`server/src/routes/chat.ts`](https://github.com/kapil31jangid/civora/blob/main/server/src/routes/chat.ts) (Chat endpoint), [`server/src/services/store.ts`](https://github.com/kapil31jangid/civora/blob/main/server/src/services/store.ts) (Conversation store), [`server/src/app.ts`](https://github.com/kapil31jangid/civora/blob/main/server/src/app.ts) (Express app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_app["Chat app<br/>[App.tsx]"]
  node_composer["Message composer<br/>[Composer.tsx]"]
  node_commands["Command palette<br/>[commands.ts]"]
  node_messageview["Message display<br/>[MessageList.tsx]"]
  node_sidebar["Conversation sidebar<br/>[Sidebar.tsx]"]
  node_dialogs["Conversation dialogs"]
  node_chatstate["Chat state<br/>[useChat.ts]"]
  node_convstate["Conversation state"]
  node_clientapi["API client<br/>[api.ts]"]
end

subgraph group_api["API workflow"]
  node_express["Express app<br/>[app.ts]"]
  node_chatroute["Chat endpoint<br/>[chat.ts]"]
  node_convroutes["Conversation endpoints<br/>[conversations.ts]"]
end

subgraph group_guidance["Guidance generation"]
  node_guard["Domain guard<br/>[domainGuard.ts]"]
  node_servercommands["Command parsing<br/>[commands.ts]"]
  node_prompts["Specialist prompts"]
  node_gemini["Response generation<br/>[gemini.ts]"]
end

subgraph group_history["Conversation history"]
  node_store["Conversation store<br/>[store.ts]"]
  node_supabase[("Supabase PostgreSQL")]
  node_memory[("In-memory store<br/>[store.ts]")]
end

node_citizen(("Citizen"))
node_geminiservice{{"Gemini API"}}

node_citizen -->|"uses chat"| node_app
node_app -->|"manages chat"| node_chatstate
node_app -->|"manages history"| node_convstate
node_app -->|"renders composer"| node_composer
node_app -->|"renders messages"| node_messageview
node_app -->|"renders sidebar"| node_sidebar
node_app -->|"renders dialogs"| node_dialogs
node_composer -->|"offers commands"| node_commands
node_chatstate -->|"sends chat"| node_clientapi
node_convstate -->|"requests history"| node_clientapi
node_clientapi -->|"calls API"| node_express
node_express -->|"routes chat"| node_chatroute
node_express -->|"routes conversations"| node_convroutes
node_chatroute -->|"parses commands"| node_servercommands
node_chatroute -->|"checks domain"| node_guard
node_chatroute -->|"requests response"| node_gemini
node_gemini -->|"selects prompt"| node_prompts
node_gemini -->|"calls model"| node_geminiservice
node_chatroute -->|"reads and writes"| node_store
node_convroutes -->|"manages history"| node_store
node_store -->|"persists records"| node_supabase
node_store -->|"falls back to"| node_memory

click node_app "https://github.com/kapil31jangid/civora/blob/main/client/src/App.tsx"
click node_composer "https://github.com/kapil31jangid/civora/blob/main/client/src/components/chat/Composer.tsx"
click node_commands "https://github.com/kapil31jangid/civora/blob/main/client/src/lib/commands.ts"
click node_messageview "https://github.com/kapil31jangid/civora/blob/main/client/src/components/chat/MessageList.tsx"
click node_sidebar "https://github.com/kapil31jangid/civora/blob/main/client/src/components/sidebar/Sidebar.tsx"
click node_dialogs "https://github.com/kapil31jangid/civora/blob/main/client/src/components/sidebar/ConversationDialogs.tsx"
click node_chatstate "https://github.com/kapil31jangid/civora/blob/main/client/src/hooks/useChat.ts"
click node_convstate "https://github.com/kapil31jangid/civora/blob/main/client/src/hooks/useConversations.ts"
click node_clientapi "https://github.com/kapil31jangid/civora/blob/main/client/src/lib/api.ts"
click node_express "https://github.com/kapil31jangid/civora/blob/main/server/src/app.ts"
click node_chatroute "https://github.com/kapil31jangid/civora/blob/main/server/src/routes/chat.ts"
click node_convroutes "https://github.com/kapil31jangid/civora/blob/main/server/src/routes/conversations.ts"
click node_guard "https://github.com/kapil31jangid/civora/blob/main/server/src/utils/domainGuard.ts"
click node_servercommands "https://github.com/kapil31jangid/civora/blob/main/server/src/utils/commands.ts"
click node_prompts "https://github.com/kapil31jangid/civora/tree/main/server/src/prompts"
click node_gemini "https://github.com/kapil31jangid/civora/blob/main/server/src/services/gemini.ts"
click node_store "https://github.com/kapil31jangid/civora/blob/main/server/src/services/store.ts"
click node_memory "https://github.com/kapil31jangid/civora/blob/main/server/src/services/store.ts"

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_composer,node_commands,node_messageview,node_sidebar,node_dialogs,node_chatstate,node_convstate,node_clientapi toneBlue
class node_express,node_chatroute,node_convroutes toneAmber
class node_guard,node_servercommands,node_prompts,node_gemini,node_geminiservice toneMint
class node_store,node_supabase,node_memory toneRose
class node_citizen toneIndigo
```

## Components

### Browser experience

- [Chat app](https://github.com/kapil31jangid/civora/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Message composer](https://github.com/kapil31jangid/civora/blob/main/client/src/components/chat/Composer.tsx): `client/src/components/chat/Composer.tsx`
- [Command palette](https://github.com/kapil31jangid/civora/blob/main/client/src/lib/commands.ts): `client/src/lib/commands.ts`
- [Message display](https://github.com/kapil31jangid/civora/blob/main/client/src/components/chat/MessageList.tsx): `client/src/components/chat/MessageList.tsx`
- [Conversation sidebar](https://github.com/kapil31jangid/civora/blob/main/client/src/components/sidebar/Sidebar.tsx): `client/src/components/sidebar/Sidebar.tsx`
- [Conversation dialogs](https://github.com/kapil31jangid/civora/blob/main/client/src/components/sidebar/ConversationDialogs.tsx): `client/src/components/sidebar/ConversationDialogs.tsx`
- [Chat state](https://github.com/kapil31jangid/civora/blob/main/client/src/hooks/useChat.ts): `client/src/hooks/useChat.ts`
- [Conversation state](https://github.com/kapil31jangid/civora/blob/main/client/src/hooks/useConversations.ts): `client/src/hooks/useConversations.ts`
- [API client](https://github.com/kapil31jangid/civora/blob/main/client/src/lib/api.ts): `client/src/lib/api.ts`

### API workflow

- [Express app](https://github.com/kapil31jangid/civora/blob/main/server/src/app.ts): `server/src/app.ts`
- [Chat endpoint](https://github.com/kapil31jangid/civora/blob/main/server/src/routes/chat.ts): `server/src/routes/chat.ts`
- [Conversation endpoints](https://github.com/kapil31jangid/civora/blob/main/server/src/routes/conversations.ts): `server/src/routes/conversations.ts`

### Guidance generation

- [Domain guard](https://github.com/kapil31jangid/civora/blob/main/server/src/utils/domainGuard.ts): `server/src/utils/domainGuard.ts`
- [Command parsing](https://github.com/kapil31jangid/civora/blob/main/server/src/utils/commands.ts): `server/src/utils/commands.ts`
- [Specialist prompts](https://github.com/kapil31jangid/civora/tree/main/server/src/prompts): `server/src/prompts`
- [Response generation](https://github.com/kapil31jangid/civora/blob/main/server/src/services/gemini.ts): `server/src/services/gemini.ts`

### Conversation history

- [Conversation store](https://github.com/kapil31jangid/civora/blob/main/server/src/services/store.ts): `server/src/services/store.ts`
- **Supabase PostgreSQL**
- [In-memory store](https://github.com/kapil31jangid/civora/blob/main/server/src/services/store.ts): `server/src/services/store.ts`

### Other components

- **Citizen**
- **Gemini API**

## Connections

- Citizen → Chat app: uses chat
- Chat app → Chat state: manages chat (evidence: `client/src/App.tsx`)
- Chat app → Conversation state: manages history (evidence: `client/src/App.tsx`)
- Chat app → Message composer: renders composer (evidence: `client/src/App.tsx`)
- Chat app → Message display: renders messages (evidence: `client/src/App.tsx`)
- Chat app → Conversation sidebar: renders sidebar (evidence: `client/src/App.tsx`)
- Chat app → Conversation dialogs: renders dialogs (evidence: `client/src/App.tsx`)
- Message composer → Command palette: offers commands (evidence: `client/src/components/chat/Composer.tsx`)
- Chat state → API client: sends chat (evidence: `client/src/hooks/useChat.ts`)
- Conversation state → API client: requests history (evidence: `client/src/hooks/useConversations.ts`)
- API client → Express app: calls API
- Express app → Chat endpoint: routes chat (evidence: `server/src/app.ts`)
- Express app → Conversation endpoints: routes conversations (evidence: `server/src/app.ts`)
- Chat endpoint → Command parsing: parses commands (evidence: `server/src/routes/chat.ts`)
- Chat endpoint → Domain guard: checks domain (evidence: `server/src/routes/chat.ts`)
- Chat endpoint → Response generation: requests response (evidence: `server/src/routes/chat.ts`)
- Response generation → Specialist prompts: selects prompt (evidence: `server/src/services/gemini.ts`)
- Response generation → Gemini API: calls model
- Chat endpoint → Conversation store: reads and writes (evidence: `server/src/routes/chat.ts`)
- Conversation endpoints → Conversation store: manages history (evidence: `server/src/routes/conversations.ts`)
- Conversation store → Supabase PostgreSQL: persists records
- Conversation store → In-memory store: falls back to (evidence: `server/src/services/store.ts`)
