# light200312/ai_council_minor_project architecture

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

- Interactive diagram: https://gitdiagram.com/light200312/ai_council_minor_project
- Repository: https://github.com/light200312/ai_council_minor_project

## Overview

AI Council is a full-stack multi-agent discussion platform. Users configure a topic, participating personas, and discussion mode in the client; backend orchestration selects speakers, invokes agent response generation, and returns discussion results and analytics. Separate features support persona management, saved conversations, combat-style debates, mentoring, and domain-specific panels. The README documents tools, memory, and provider routing; source excerpts/index confirm core calls and imports. Some UI and panel internals were not sampled, so their links are limited to documented capabilities or indexed references.

Main entry points: [`backend/server.js`](https://github.com/light200312/ai_council_minor_project/blob/main/backend/server.js) (HTTP server), [`frontend/src/App.jsx`](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/App.jsx) (Council app), [`backend/features/orchestrator/orchestrator.service.js`](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.service.js) (Speaker selection), [`backend/features/agent/agentRuntime.service.js`](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agentRuntime.service.js) (Agent response runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["Council app<br/>[App.jsx]"]
  node_store["Session store<br/>[useAppStore.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_analytics["Discussion analytics<br/>[LiveAnalytics.jsx]"]
  node_verdict["Verdict reports"]
  node_panels_ui["Learning panels"]
  node_mock_catalog["Client sample data<br/>[mockData.js]"]
end

subgraph group_api["Backend features"]
  node_server["HTTP server<br/>[server.js]"]
  node_auth["Authentication<br/>[auth.controller.js]"]
  node_agents["Persona management"]
  node_orchestrator_routes["Orchestration endpoint"]
  node_orchestrator_controller["Orchestration handler"]
  node_combat["Debate rounds<br/>[combat.service.js]"]
  node_messages["Conversation history"]
  node_panels["Domain panels<br/>[panels.service.js]"]
end

subgraph group_runtime["AI runtime"]
  node_agent_creator["Persona generation"]
  node_orchestrator["Speaker selection"]
  node_agent_runtime["Agent response runtime"]
  node_memory["Conversation memory<br/>[memoryService.js]"]
end

subgraph group_state["Persistence and shared state"]
  node_agent_data[("Persona catalog<br/>[agent.model.js]")]
  node_message_data[("Message records<br/>[message.model.js]")]
  node_report_data[("Discussion reports")]
  node_topic_memory[("Topic memory")]
  node_prebuilt["Prebuilt personas<br/>[preBuildAgents.js]"]
end

subgraph group_providers["Models and tools"]
  node_llm["LLM client<br/>[llmClient.js]"]
  node_model_registry["Model routing"]
  node_tools["Tool execution<br/>[tools.js]"]
end

node_user(("User"))
node_knowledge{{"External knowledge"}}

node_user -->|"configures discussion"| node_app
node_app -->|"reads session state"| node_store
node_store -->|"requests data"| node_api_client
node_app -->|"renders analytics"| node_analytics
node_app -->|"renders reports"| node_verdict
node_app -->|"offers panel views"| node_panels_ui
node_api_client -.->|"calls API"| node_server
node_server -->|"mounts routes"| node_auth
node_server -->|"mounts routes"| node_agents
node_server -->|"mounts routes"| node_orchestrator_routes
node_server -->|"mounts debate routes"| node_combat
node_server -->|"mounts message routes"| node_messages
node_server -->|"mounts panel routes"| node_panels
node_agents -->|"creates and queries"| node_agent_data
node_agents -->|"requests drafts"| node_agent_creator
node_orchestrator_routes -->|"routes request"| node_orchestrator_controller
node_orchestrator_controller -->|"delegates task"| node_orchestrator
node_orchestrator -->|"runs selected agent"| node_agent_runtime
node_orchestrator -->|"selects speaker"| node_llm
node_orchestrator -->|"loads candidates"| node_agent_data
node_agent_runtime -->|"generates response"| node_llm
node_agent_runtime -->|"uses tools"| node_tools
node_agent_runtime -->|"uses conversation memory"| node_memory
node_agent_runtime -->|"routes persona model"| node_model_registry
node_llm -->|"resolves local model"| node_model_registry
node_tools -->|"queries sources"| node_knowledge
node_memory -->|"reads and writes"| node_topic_memory
node_combat -->|"uses personas"| node_agent_data
node_messages -->|"reads and writes"| node_message_data
node_messages -->|"loads reports"| node_report_data
node_panels -->|"uses preset personas"| node_prebuilt
node_store -->|"loads sample data"| node_mock_catalog
node_orchestrator -.->|"returns trace and metrics"| node_analytics
node_user -.->|"authenticates"| node_auth

click node_app "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/App.jsx"
click node_store "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/store/useAppStore.js"
click node_api_client "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/lib/api.js"
click node_analytics "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/components/LiveAnalytics.jsx"
click node_verdict "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/components/VerdictReportViewer.jsx"
click node_panels_ui "https://github.com/light200312/ai_council_minor_project/tree/main/frontend/src/components"
click node_server "https://github.com/light200312/ai_council_minor_project/blob/main/backend/server.js"
click node_auth "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/auth/auth.controller.js"
click node_agents "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agent.controller.js"
click node_agent_creator "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agentCreator.service.js"
click node_orchestrator_routes "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.routes.js"
click node_orchestrator_controller "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.controller.js"
click node_orchestrator "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.service.js"
click node_agent_runtime "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agentRuntime.service.js"
click node_combat "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/combat/combat.service.js"
click node_messages "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/message.controller.js"
click node_panels "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/panels/panels.service.js"
click node_agent_data "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agent.model.js"
click node_message_data "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/message.model.js"
click node_report_data "https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/discussionReport.model.js"
click node_memory "https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/memoryService.js"
click node_topic_memory "https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/topicMemory.model.js"
click node_llm "https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/llmClient.js"
click node_model_registry "https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/agentModelRegistry.js"
click node_tools "https://github.com/light200312/ai_council_minor_project/blob/main/backend/tools/tools.js"
click node_prebuilt "https://github.com/light200312/ai_council_minor_project/blob/main/backend/data/preBuildAgents.js"
click node_mock_catalog "https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/data/mockData.js"

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_store,node_api_client,node_analytics,node_verdict,node_panels_ui,node_mock_catalog,node_user toneBlue
class node_server,node_auth,node_agents,node_orchestrator_routes,node_orchestrator_controller,node_combat,node_messages,node_panels toneAmber
class node_agent_creator,node_orchestrator,node_agent_runtime,node_memory toneMint
class node_agent_data,node_message_data,node_report_data,node_topic_memory,node_prebuilt toneRose
class node_llm,node_model_registry,node_tools,node_knowledge toneIndigo
```

## Components

### Client experience

- [Council app](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session store](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/store/useAppStore.js): `frontend/src/store/useAppStore.js`
- [API client](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`
- [Discussion analytics](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/components/LiveAnalytics.jsx): `frontend/src/components/LiveAnalytics.jsx`
- [Verdict reports](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/components/VerdictReportViewer.jsx): `frontend/src/components/VerdictReportViewer.jsx`
- [Learning panels](https://github.com/light200312/ai_council_minor_project/tree/main/frontend/src/components): `frontend/src/components`
- [Client sample data](https://github.com/light200312/ai_council_minor_project/blob/main/frontend/src/data/mockData.js): `frontend/src/data/mockData.js`

### Backend features

- [HTTP server](https://github.com/light200312/ai_council_minor_project/blob/main/backend/server.js): `backend/server.js`
- [Authentication](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/auth/auth.controller.js): `backend/features/auth/auth.controller.js`
- [Persona management](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agent.controller.js): `backend/features/agent/agent.controller.js`
- [Orchestration endpoint](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.routes.js): `backend/features/orchestrator/orchestrator.routes.js`
- [Orchestration handler](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.controller.js): `backend/features/orchestrator/orchestrator.controller.js`
- [Debate rounds](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/combat/combat.service.js): `backend/features/combat/combat.service.js`
- [Conversation history](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/message.controller.js): `backend/features/message/message.controller.js`
- [Domain panels](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/panels/panels.service.js): `backend/features/panels/panels.service.js`

### AI runtime

- [Persona generation](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agentCreator.service.js): `backend/features/agent/agentCreator.service.js`
- [Speaker selection](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/orchestrator/orchestrator.service.js): `backend/features/orchestrator/orchestrator.service.js`
- [Agent response runtime](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agentRuntime.service.js): `backend/features/agent/agentRuntime.service.js`
- [Conversation memory](https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/memoryService.js): `backend/shared/memoryService.js`

### Persistence and shared state

- [Persona catalog](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/agent/agent.model.js): `backend/features/agent/agent.model.js`
- [Message records](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/message.model.js): `backend/features/message/message.model.js`
- [Discussion reports](https://github.com/light200312/ai_council_minor_project/blob/main/backend/features/message/discussionReport.model.js): `backend/features/message/discussionReport.model.js`
- [Topic memory](https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/topicMemory.model.js): `backend/shared/topicMemory.model.js`
- [Prebuilt personas](https://github.com/light200312/ai_council_minor_project/blob/main/backend/data/preBuildAgents.js): `backend/data/preBuildAgents.js`

### Models and tools

- [LLM client](https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/llmClient.js): `backend/shared/llmClient.js`
- [Model routing](https://github.com/light200312/ai_council_minor_project/blob/main/backend/shared/agentModelRegistry.js): `backend/shared/agentModelRegistry.js`
- [Tool execution](https://github.com/light200312/ai_council_minor_project/blob/main/backend/tools/tools.js): `backend/tools/tools.js`

### Other components

- **User**
- **External knowledge**

## Connections

- User → Council app: configures discussion (evidence: `README.md`)
- Council app → Session store: reads session state (evidence: `frontend/src/App.jsx`)
- Session store → API client: requests data (evidence: `frontend/src/store/useAppStore.js`)
- Council app → Discussion analytics: renders analytics (evidence: `frontend/src/App.jsx`)
- Council app → Verdict reports: renders reports (evidence: `frontend/src/App.jsx`)
- Council app → Learning panels: offers panel views (evidence: `frontend/src/App.jsx`)
- API client → HTTP server: calls API
- HTTP server → Authentication: mounts routes (evidence: `backend/server.js`)
- HTTP server → Persona management: mounts routes (evidence: `backend/server.js`)
- HTTP server → Orchestration endpoint: mounts routes (evidence: `backend/server.js`)
- HTTP server → Debate rounds: mounts debate routes (evidence: `backend/server.js`)
- HTTP server → Conversation history: mounts message routes (evidence: `backend/server.js`)
- HTTP server → Domain panels: mounts panel routes (evidence: `backend/server.js`)
- Persona management → Persona catalog: creates and queries (evidence: `backend/features/agent/agent.controller.js`)
- Persona management → Persona generation: requests drafts (evidence: `backend/features/agent/agent.controller.js`)
- Orchestration endpoint → Orchestration handler: routes request (evidence: `backend/features/orchestrator/orchestrator.routes.js`)
- Orchestration handler → Speaker selection: delegates task (evidence: `backend/features/orchestrator/orchestrator.controller.js`)
- Speaker selection → Agent response runtime: runs selected agent (evidence: `backend/features/orchestrator/orchestrator.service.js`)
- Speaker selection → LLM client: selects speaker (evidence: `backend/features/orchestrator/orchestrator.service.js`)
- Speaker selection → Persona catalog: loads candidates (evidence: `backend/features/orchestrator/orchestrator.service.js`)
- Agent response runtime → LLM client: generates response (evidence: `backend/features/agent/agentRuntime.service.js`)
- Agent response runtime → Tool execution: uses tools (evidence: `backend/features/agent/agentRuntime.service.js`)
- Agent response runtime → Conversation memory: uses conversation memory (evidence: `backend/features/agent/agentRuntime.service.js`)
- Agent response runtime → Model routing: routes persona model (evidence: `backend/features/agent/agentRuntime.service.js`)
- LLM client → Model routing: resolves local model (evidence: `backend/shared/llmClient.js`)
- Tool execution → External knowledge: queries sources (evidence: `README.md`)
- Conversation memory → Topic memory: reads and writes (evidence: `backend/shared/memoryService.js`)
- Debate rounds → Persona catalog: uses personas (evidence: `backend/features/combat/combat.service.js`)
- Conversation history → Message records: reads and writes (evidence: `backend/features/message/message.controller.js`)
- Conversation history → Discussion reports: loads reports (evidence: `backend/features/message/message.controller.js`)
- Domain panels → Prebuilt personas: uses preset personas (evidence: `backend/features/panels/panels.service.js`)
- Session store → Client sample data: loads sample data (evidence: `frontend/src/store/useAppStore.js`)
- Speaker selection → Discussion analytics: returns trace and metrics (evidence: `README.md`)
- User → Authentication: authenticates
