# dami904/celo_mind architecture

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

- Interactive diagram: https://gitdiagram.com/dami904/celo_mind
- Repository: https://github.com/dami904/celo_mind

## Overview

CeloMind is a Celo blockchain assistant exposed through a web dashboard/chat and an MCP interface. The main user workflow is to connect a wallet, ask in natural language, route the request to the relevant blockchain or information capability, and receive an explanation or unsigned transaction to review and sign locally. The graph preserves wallet, market, risk, whale, DeFi, docs, and analytics capabilities described in the README. Route-level wiring beyond the sampled chat handler is based on the documented product surface; those links are limited to explicit entry points.

Main entry points: [`backend/apps/api/src/routes/chat.ts`](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/routes/chat.ts) (Chat handler), [`backend/apps/api/src/server.ts`](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/server.ts) (Fastify API), [`frontend/src/app/chat/page.jsx`](https://github.com/dami904/celo_mind/blob/main/frontend/src/app/chat/page.jsx) (Web chat), [`frontend/src/app/dashboard/page.jsx`](https://github.com/dami904/celo_mind/blob/main/frontend/src/app/dashboard/page.jsx) (Portfolio dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webchat["Web chat<br/>[page.jsx]"]
  node_dashboard["Portfolio dashboard<br/>[page.jsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and orchestration"]
  node_server["Fastify API<br/>[server.ts]"]
  node_chat_route["Chat handler<br/>[chat.ts]"]
  node_intent["Intent routing<br/>[intent-router.ts]"]
  node_providers["AI providers<br/>[providers.ts]"]
  node_mcp_http["MCP HTTP entry<br/>[mcp-http.ts]"]
  node_chat_db[("Conversation history<br/>[sqlite.ts]")]
end

subgraph group_tools["Celo capabilities"]
  node_wallet_tools["Wallet and transfers<br/>[celo-client.ts]"]
  node_market_tools["Market intelligence<br/>[market.ts]"]
  node_risk_tools["Token risk<br/>[risk.ts]"]
  node_whale_tools["Whale tracking<br/>[whale.ts]"]
  node_defi_tools["DeFi operations<br/>[aave.ts]"]
end

subgraph group_knowledge["Knowledge and metrics"]
  node_docs["Celo docs knowledge<br/>[index.ts]"]
  node_docs_fetch["Live docs fetch<br/>[live-fetch.ts]"]
  node_metrics["Usage metrics<br/>[index.ts]"]
  node_metrics_store[("Metrics store<br/>[store.ts]")]
end

node_user(("User"))
node_wallet(("Connected wallet"))
node_celo_chain{{"Celo network"}}
node_data_sources{{"Market and explorer sources"}}
node_ai_service{{"AI services"}}

node_user -->|"asks"| node_webchat
node_user -->|"views"| node_dashboard
node_webchat -->|"sends chat"| node_api_client
node_dashboard -->|"fetches data"| node_api_client
node_api_client -->|"HTTP requests"| node_server
node_server -->|"dispatches"| node_chat_route
node_server -->|"dispatches"| node_mcp_http
node_server -->|"registers routes"| node_metrics
node_chat_route -->|"resolves intent"| node_intent
node_chat_route -->|"requests completion"| node_providers
node_providers -.->|"calls"| node_ai_service
node_chat_route -->|"reads or prepares"| node_wallet_tools
node_chat_route -->|"queries"| node_market_tools
node_chat_route -->|"checks"| node_risk_tools
node_chat_route -->|"queries"| node_whale_tools
node_chat_route -->|"prepares actions"| node_defi_tools
node_mcp_http -->|"dispatches tools"| node_wallet_tools
node_wallet_tools -->|"reads or writes"| node_celo_chain
node_market_tools -->|"queries"| node_data_sources
node_risk_tools -->|"queries"| node_data_sources
node_whale_tools -->|"queries"| node_data_sources
node_defi_tools -->|"reads or prepares"| node_celo_chain
node_chat_route -->|"answers doc queries"| node_docs
node_docs -.->|"fetches live docs"| node_docs_fetch
node_chat_route -->|"reads and writes history"| node_chat_db
node_dashboard -->|"connects"| node_wallet
node_webchat -->|"requests signature"| node_wallet
node_wallet -->|"signs confirmed tx"| node_celo_chain
node_metrics -->|"records and reads"| node_metrics_store

click node_webchat "https://github.com/dami904/celo_mind/blob/main/frontend/src/app/chat/page.jsx"
click node_dashboard "https://github.com/dami904/celo_mind/blob/main/frontend/src/app/dashboard/page.jsx"
click node_api_client "https://github.com/dami904/celo_mind/blob/main/frontend/src/lib/api.ts"
click node_server "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/server.ts"
click node_chat_route "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/routes/chat.ts"
click node_intent "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/ai/intent-router.ts"
click node_providers "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/ai/providers.ts"
click node_mcp_http "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/routes/mcp-http.ts"
click node_wallet_tools "https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/celo-client.ts"
click node_market_tools "https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/market.ts"
click node_risk_tools "https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/risk.ts"
click node_whale_tools "https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/whale.ts"
click node_defi_tools "https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/aave.ts"
click node_docs "https://github.com/dami904/celo_mind/blob/main/backend/packages/docs-knowledge/src/index.ts"
click node_docs_fetch "https://github.com/dami904/celo_mind/blob/main/backend/packages/docs-knowledge/src/live-fetch.ts"
click node_metrics "https://github.com/dami904/celo_mind/blob/main/backend/dashboard/src/index.ts"
click node_metrics_store "https://github.com/dami904/celo_mind/blob/main/backend/dashboard/src/store.ts"
click node_chat_db "https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/db/sqlite.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_webchat,node_dashboard,node_api_client,node_user toneBlue
class node_server,node_chat_route,node_intent,node_providers,node_mcp_http,node_chat_db toneAmber
class node_wallet_tools,node_market_tools,node_risk_tools,node_whale_tools,node_defi_tools toneMint
class node_docs,node_docs_fetch,node_metrics,node_metrics_store toneRose
class node_wallet,node_celo_chain,node_data_sources,node_ai_service toneIndigo
```

## Components

### Web experience

- [Web chat](https://github.com/dami904/celo_mind/blob/main/frontend/src/app/chat/page.jsx): `frontend/src/app/chat/page.jsx`
- [Portfolio dashboard](https://github.com/dami904/celo_mind/blob/main/frontend/src/app/dashboard/page.jsx): `frontend/src/app/dashboard/page.jsx`
- [API client](https://github.com/dami904/celo_mind/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### API and orchestration

- [Fastify API](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/server.ts): `backend/apps/api/src/server.ts`
- [Chat handler](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/routes/chat.ts): `backend/apps/api/src/routes/chat.ts`
- [Intent routing](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/ai/intent-router.ts): `backend/apps/api/src/ai/intent-router.ts`
- [AI providers](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/ai/providers.ts): `backend/apps/api/src/ai/providers.ts`
- [MCP HTTP entry](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/routes/mcp-http.ts): `backend/apps/api/src/routes/mcp-http.ts`
- [Conversation history](https://github.com/dami904/celo_mind/blob/main/backend/apps/api/src/db/sqlite.ts): `backend/apps/api/src/db/sqlite.ts`

### Celo capabilities

- [Wallet and transfers](https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/celo-client.ts): `backend/packages/mcp-server/src/celo-client.ts`
- [Market intelligence](https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/market.ts): `backend/packages/mcp-server/src/market.ts`
- [Token risk](https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/risk.ts): `backend/packages/mcp-server/src/risk.ts`
- [Whale tracking](https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/whale.ts): `backend/packages/mcp-server/src/whale.ts`
- [DeFi operations](https://github.com/dami904/celo_mind/blob/main/backend/packages/mcp-server/src/aave.ts): `backend/packages/mcp-server/src/aave.ts`

### Knowledge and metrics

- [Celo docs knowledge](https://github.com/dami904/celo_mind/blob/main/backend/packages/docs-knowledge/src/index.ts): `backend/packages/docs-knowledge/src/index.ts`
- [Live docs fetch](https://github.com/dami904/celo_mind/blob/main/backend/packages/docs-knowledge/src/live-fetch.ts): `backend/packages/docs-knowledge/src/live-fetch.ts`
- [Usage metrics](https://github.com/dami904/celo_mind/blob/main/backend/dashboard/src/index.ts): `backend/dashboard/src/index.ts`
- [Metrics store](https://github.com/dami904/celo_mind/blob/main/backend/dashboard/src/store.ts): `backend/dashboard/src/store.ts`

### Other components

- **User**
- **Connected wallet**
- **Celo network**
- **Market and explorer sources**
- **AI services**

## Connections

- User → Web chat: asks
- User → Portfolio dashboard: views
- Web chat → API client: sends chat
- Portfolio dashboard → API client: fetches data
- API client → Fastify API: HTTP requests
- Fastify API → Chat handler: dispatches
- Fastify API → MCP HTTP entry: dispatches
- Fastify API → Usage metrics: registers routes
- Chat handler → Intent routing: resolves intent
- Chat handler → AI providers: requests completion
- AI providers → AI services: calls
- Chat handler → Wallet and transfers: reads or prepares
- Chat handler → Market intelligence: queries
- Chat handler → Token risk: checks
- Chat handler → Whale tracking: queries
- Chat handler → DeFi operations: prepares actions
- MCP HTTP entry → Wallet and transfers: dispatches tools
- Wallet and transfers → Celo network: reads or writes
- Market intelligence → Market and explorer sources: queries
- Token risk → Market and explorer sources: queries
- Whale tracking → Market and explorer sources: queries
- DeFi operations → Celo network: reads or prepares
- Chat handler → Celo docs knowledge: answers doc queries
- Celo docs knowledge → Live docs fetch: fetches live docs
- Chat handler → Conversation history: reads and writes history
- Portfolio dashboard → Connected wallet: connects
- Web chat → Connected wallet: requests signature
- Connected wallet → Celo network: signs confirmed tx
- Usage metrics → Metrics store: records and reads