# devfiqi/colorstack-ai architecture

> Architecture diagram of the GitHub repository devfiqi/colorstack-ai, 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/devfiqi/colorstack-ai
- Repository: https://github.com/devfiqi/colorstack-ai

## Overview

ColorStack AI turns Discord conversations into persistent organizational facts, reconciles them into current state, evaluates event readiness, and builds bounded context for executive reasoning and daily briefs. Users can inspect operational data through a read-only local dashboard. The README documents the major workflow and capabilities; source-index relationships support several internal links, but unsampled implementations and frontend request wiring are not inferred.

Main entry points: [`src/colorstack_ai/db/session.py`](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/db/session.py) (PostgreSQL), [`src/colorstack_ai/context/builder.py`](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/builder.py) (Context builder), [`src/colorstack_ai/briefing/service.py`](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/service.py) (Brief generation), [`src/colorstack_ai/reasoning/service.py`](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/reasoning/service.py) (Cloud reasoning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Discord ingestion"]
  node_bot["Discord bot<br/>[client.py]"]
  node_ingestion["Message ingestion"]
end

subgraph group_operations["Organizational operations"]
  node_extract["Local extraction"]
  node_state["Organizational state"]
  node_playbooks["Event playbooks"]
  node_requirements["Requirement evaluation"]
end

subgraph group_intelligence["Context and reasoning"]
  node_context["Context builder<br/>[builder.py]"]
  node_retrieval["Bounded retrieval<br/>[retrieval.py]"]
  node_query["Query interpretation<br/>[query_parser.py]"]
  node_reasoning["Cloud reasoning<br/>[service.py]"]
  node_provider["Reasoning provider<br/>[openai.py]"]
end

subgraph group_delivery["Briefing and dashboard"]
  node_brief["Brief generation<br/>[service.py]"]
  node_brief_format["Brief formatting<br/>[formatter.py]"]
  node_brief_delivery["Brief delivery<br/>[delivery.py]"]
  node_api["Dashboard API<br/>[service.py]"]
  node_routes["API routes<br/>[dashboard.py]"]
  node_frontend["Dashboard interface"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL<br/>[session.py]")]
end

node_discord(("Discord server"))
node_user(("Dashboard user"))

node_discord -->|"sends messages"| node_bot
node_bot -->|"ingests messages"| node_ingestion
node_ingestion -->|"stores raw messages"| node_postgres
node_postgres -->|"supplies messages"| node_extract
node_extract -->|"stores extracted facts"| node_postgres
node_state -->|"persists current state"| node_postgres
node_playbooks -->|"stores playbooks"| node_postgres
node_requirements -->|"stores evaluations"| node_postgres
node_context -->|"builds from retrieval"| node_retrieval
node_retrieval -->|"reads organizational data"| node_postgres
node_query -.->|"interprets queries"| node_context
node_context -->|"provides bounded context"| node_reasoning
node_reasoning -->|"invokes provider"| node_provider
node_provider -.->|"returns response"| node_reasoning
node_context -->|"supplies organization context"| node_brief
node_brief -->|"requests reasoning"| node_reasoning
node_brief -->|"formats brief"| node_brief_format
node_brief -->|"records brief runs"| node_postgres
node_brief_delivery -->|"delivers executive brief"| node_discord
node_routes -->|"routes dashboard requests"| node_api
node_api -->|"builds dashboard context"| node_context
node_api -->|"reads dashboard data"| node_postgres
node_user -->|"views dashboard"| node_frontend
node_frontend -.->|"requests dashboard data"| node_routes

click node_bot "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/discord/client.py"
click node_ingestion "https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/ingestion"
click node_extract "https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/extraction"
click node_state "https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/state"
click node_playbooks "https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/playbooks"
click node_requirements "https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/requirements"
click node_context "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/builder.py"
click node_retrieval "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/retrieval.py"
click node_query "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/query_parser.py"
click node_reasoning "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/reasoning/service.py"
click node_provider "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/reasoning/providers/openai.py"
click node_brief "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/service.py"
click node_brief_format "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/formatter.py"
click node_brief_delivery "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/delivery.py"
click node_api "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/api/service.py"
click node_routes "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/api/routes/dashboard.py"
click node_frontend "https://github.com/devfiqi/colorstack-ai/tree/main/frontend/src/routes"
click node_postgres "https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/db/session.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_bot,node_ingestion,node_user toneBlue
class node_extract,node_state,node_playbooks,node_requirements toneAmber
class node_context,node_retrieval,node_query,node_reasoning,node_provider,node_discord toneMint
class node_brief,node_brief_format,node_brief_delivery,node_api,node_routes,node_frontend toneRose
class node_postgres toneIndigo
```

## Components

### Discord ingestion

- [Discord bot](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/discord/client.py): `src/colorstack_ai/discord/client.py`
- [Message ingestion](https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/ingestion): `src/colorstack_ai/ingestion`

### Organizational operations

- [Local extraction](https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/extraction): `src/colorstack_ai/extraction`
- [Organizational state](https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/state): `src/colorstack_ai/state`
- [Event playbooks](https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/playbooks): `src/colorstack_ai/playbooks`
- [Requirement evaluation](https://github.com/devfiqi/colorstack-ai/tree/main/src/colorstack_ai/requirements): `src/colorstack_ai/requirements`

### Context and reasoning

- [Context builder](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/builder.py): `src/colorstack_ai/context/builder.py`
- [Bounded retrieval](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/retrieval.py): `src/colorstack_ai/context/retrieval.py`
- [Query interpretation](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/context/query_parser.py): `src/colorstack_ai/context/query_parser.py`
- [Cloud reasoning](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/reasoning/service.py): `src/colorstack_ai/reasoning/service.py`
- [Reasoning provider](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/reasoning/providers/openai.py): `src/colorstack_ai/reasoning/providers/openai.py`

### Briefing and dashboard

- [Brief generation](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/service.py): `src/colorstack_ai/briefing/service.py`
- [Brief formatting](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/formatter.py): `src/colorstack_ai/briefing/formatter.py`
- [Brief delivery](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/briefing/delivery.py): `src/colorstack_ai/briefing/delivery.py`
- [Dashboard API](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/api/service.py): `src/colorstack_ai/api/service.py`
- [API routes](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/api/routes/dashboard.py): `src/colorstack_ai/api/routes/dashboard.py`
- [Dashboard interface](https://github.com/devfiqi/colorstack-ai/tree/main/frontend/src/routes): `frontend/src/routes`

### Persistence

- [PostgreSQL](https://github.com/devfiqi/colorstack-ai/blob/main/src/colorstack_ai/db/session.py): `src/colorstack_ai/db/session.py`

### Other components

- **Discord server**
- **Dashboard user**

## Connections

- Discord server → Discord bot: sends messages (evidence: `README.md`)
- Discord bot → Message ingestion: ingests messages (evidence: `src/colorstack_ai/discord/client.py`)
- Message ingestion → PostgreSQL: stores raw messages (evidence: `README.md`)
- PostgreSQL → Local extraction: supplies messages (evidence: `README.md`)
- Local extraction → PostgreSQL: stores extracted facts (evidence: `README.md`)
- Organizational state → PostgreSQL: persists current state (evidence: `README.md`)
- Event playbooks → PostgreSQL: stores playbooks (evidence: `README.md`)
- Requirement evaluation → PostgreSQL: stores evaluations (evidence: `README.md`)
- Context builder → Bounded retrieval: builds from retrieval (evidence: `src/colorstack_ai/context/builder.py`)
- Bounded retrieval → PostgreSQL: reads organizational data (evidence: `src/colorstack_ai/context/retrieval.py`)
- Query interpretation → Context builder: interprets queries (evidence: `src/colorstack_ai/context/builder.py`)
- Context builder → Cloud reasoning: provides bounded context (evidence: `README.md`)
- Cloud reasoning → Reasoning provider: invokes provider (evidence: `src/colorstack_ai/reasoning/service.py`)
- Reasoning provider → Cloud reasoning: returns response
- Context builder → Brief generation: supplies organization context (evidence: `src/colorstack_ai/briefing/service.py`)
- Brief generation → Cloud reasoning: requests reasoning (evidence: `src/colorstack_ai/briefing/service.py`)
- Brief generation → Brief formatting: formats brief (evidence: `src/colorstack_ai/briefing/service.py`)
- Brief generation → PostgreSQL: records brief runs
- Brief delivery → Discord server: delivers executive brief (evidence: `README.md`)
- API routes → Dashboard API: routes dashboard requests (evidence: `src/colorstack_ai/api/routes/dashboard.py`)
- Dashboard API → Context builder: builds dashboard context (evidence: `src/colorstack_ai/api/service.py`)
- Dashboard API → PostgreSQL: reads dashboard data (evidence: `src/colorstack_ai/api/service.py`)
- Dashboard user → Dashboard interface: views dashboard (evidence: `README.md`)
- Dashboard interface → API routes: requests dashboard data
