# robjvan/icos-v3 architecture

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

- Interactive diagram: https://gitdiagram.com/robjvan/icos-v3
- Repository: https://github.com/robjvan/icos-v3

## Overview

ICOS is an experimental cognitive-agent runtime with an Angular web client. The principal workflow is a user conversation handled by the core, routed through a provider-independent model boundary, persisted as a session, and enriched by recall; extracted memory can later be reviewed and promoted with human approval. The graph also preserves documented skills, tools, MCP, security, and administration capabilities. Some subsystem links are documented in the README rather than shown in sampled implementation; those edges cite the README.

Main entry points: [`core/src/conversation/conversation.service.ts`](https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.service.ts) (Conversation service), [`web-client/src/app/services/core-api.service.ts`](https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/services/core-api.service.ts) (Core API client), [`web-client/src/app/components/chat-ui-component/chat-ui-component.ts`](https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/components/chat-ui-component/chat-ui-component.ts) (Chat interface), [`core/src/conversation/conversation.controller.ts`](https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.controller.ts) (Conversation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_chat["Chat interface"]
  node_webapi["Core API client"]
  node_review["Memory review UI"]
end

subgraph group_api["Core API"]
  node_conversation["Conversation API"]
  node_approval["Human approvals"]
  node_clarification["Clarification queue"]
  node_auth["Authentication<br/>[auth.service.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_convservice["Conversation service"]
  node_llm["LLM client<br/>[llm.client.ts]"]
  node_skills["Skills<br/>[skill.service.ts]"]
  node_tools["Tool execution"]
  node_mcp["MCP bridge"]
end

subgraph group_knowledge["Memory system"]
  node_memory["Memory recall<br/>[recall.service.ts]"]
  node_candidates["Candidate extraction"]
  node_claims[("Epistemic claims")]
  node_promotion["Memory promotion"]
end

subgraph group_platform["Persistence and integrations"]
  node_provider["Provider registry"]
  node_sessions["Session store<br/>[session.store.ts]"]
  node_sqlite[("SQLite sessions")]
end

node_user(("User"))

node_user -->|"sends message"| node_chat
node_chat -.->|"submits chat"| node_webapi
node_webapi -->|"calls REST"| node_conversation
node_conversation -.->|"handles turn"| node_convservice
node_convservice -->|"requests completion"| node_llm
node_llm -->|"resolves provider"| node_provider
node_convservice -->|"persists transcript"| node_sessions
node_sessions -->|"stores sessions"| node_sqlite
node_convservice -->|"retrieves context"| node_memory
node_convservice -->|"extracts candidates"| node_candidates
node_candidates -.->|"supports knowledge"| node_claims
node_review -->|"requests review data"| node_webapi
node_webapi -->|"resolves approval"| node_approval
node_approval -->|"authorizes promotion"| node_promotion
node_promotion -.->|"updates beliefs"| node_claims
node_convservice -->|"uses capabilities"| node_skills
node_convservice -->|"executes tools"| node_tools
node_tools -->|"bridges external tools"| node_mcp
node_convservice -->|"queues questions"| node_clarification
node_webapi -.->|"authenticates requests"| node_auth

click node_chat "https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/components/chat-ui-component/chat-ui-component.ts"
click node_webapi "https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/services/core-api.service.ts"
click node_review "https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/components/memory-review-queue/memory-review-queue.ts"
click node_conversation "https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.controller.ts"
click node_convservice "https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.service.ts"
click node_llm "https://github.com/robjvan/icos-v3/blob/master/core/src/llm/llm.client.ts"
click node_provider "https://github.com/robjvan/icos-v3/blob/master/core/src/providers/provider-registry.service.ts"
click node_skills "https://github.com/robjvan/icos-v3/blob/master/core/src/skills/skill.service.ts"
click node_tools "https://github.com/robjvan/icos-v3/blob/master/core/src/tools/tool-execution.service.ts"
click node_mcp "https://github.com/robjvan/icos-v3/blob/master/core/src/mcp/mcp-tool-bridge.service.ts"
click node_sessions "https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/session.store.ts"
click node_sqlite "https://github.com/robjvan/icos-v3/blob/master/core/src/session/sqlite-session.repository.ts"
click node_memory "https://github.com/robjvan/icos-v3/blob/master/core/src/memory/recall.service.ts"
click node_candidates "https://github.com/robjvan/icos-v3/blob/master/core/src/memory/llm-memory-candidate-extractor.ts"
click node_claims "https://github.com/robjvan/icos-v3/blob/master/core/src/memory/claim.repository.ts"
click node_promotion "https://github.com/robjvan/icos-v3/blob/master/core/src/memory/promotion.service.ts"
click node_approval "https://github.com/robjvan/icos-v3/blob/master/core/src/approvals/approval.service.ts"
click node_clarification "https://github.com/robjvan/icos-v3/blob/master/core/src/clarifications/clarification.service.ts"
click node_auth "https://github.com/robjvan/icos-v3/blob/master/core/src/auth/auth.service.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_chat,node_webapi,node_review,node_user toneBlue
class node_conversation,node_approval,node_clarification,node_auth toneAmber
class node_convservice,node_llm,node_skills,node_tools,node_mcp toneMint
class node_memory,node_candidates,node_claims,node_promotion toneRose
class node_provider,node_sessions,node_sqlite toneIndigo
```

## Components

### Web client

- [Chat interface](https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/components/chat-ui-component/chat-ui-component.ts): `web-client/src/app/components/chat-ui-component/chat-ui-component.ts`
- [Core API client](https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/services/core-api.service.ts): `web-client/src/app/services/core-api.service.ts`
- [Memory review UI](https://github.com/robjvan/icos-v3/blob/master/web-client/src/app/components/memory-review-queue/memory-review-queue.ts): `web-client/src/app/components/memory-review-queue/memory-review-queue.ts`

### Core API

- [Conversation API](https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.controller.ts): `core/src/conversation/conversation.controller.ts`
- [Human approvals](https://github.com/robjvan/icos-v3/blob/master/core/src/approvals/approval.service.ts): `core/src/approvals/approval.service.ts`
- [Clarification queue](https://github.com/robjvan/icos-v3/blob/master/core/src/clarifications/clarification.service.ts): `core/src/clarifications/clarification.service.ts`
- [Authentication](https://github.com/robjvan/icos-v3/blob/master/core/src/auth/auth.service.ts): `core/src/auth/auth.service.ts`

### Agent runtime

- [Conversation service](https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/conversation.service.ts): `core/src/conversation/conversation.service.ts`
- [LLM client](https://github.com/robjvan/icos-v3/blob/master/core/src/llm/llm.client.ts): `core/src/llm/llm.client.ts`
- [Skills](https://github.com/robjvan/icos-v3/blob/master/core/src/skills/skill.service.ts): `core/src/skills/skill.service.ts`
- [Tool execution](https://github.com/robjvan/icos-v3/blob/master/core/src/tools/tool-execution.service.ts): `core/src/tools/tool-execution.service.ts`
- [MCP bridge](https://github.com/robjvan/icos-v3/blob/master/core/src/mcp/mcp-tool-bridge.service.ts): `core/src/mcp/mcp-tool-bridge.service.ts`

### Memory system

- [Memory recall](https://github.com/robjvan/icos-v3/blob/master/core/src/memory/recall.service.ts): `core/src/memory/recall.service.ts`
- [Candidate extraction](https://github.com/robjvan/icos-v3/blob/master/core/src/memory/llm-memory-candidate-extractor.ts): `core/src/memory/llm-memory-candidate-extractor.ts`
- [Epistemic claims](https://github.com/robjvan/icos-v3/blob/master/core/src/memory/claim.repository.ts): `core/src/memory/claim.repository.ts`
- [Memory promotion](https://github.com/robjvan/icos-v3/blob/master/core/src/memory/promotion.service.ts): `core/src/memory/promotion.service.ts`

### Persistence and integrations

- [Provider registry](https://github.com/robjvan/icos-v3/blob/master/core/src/providers/provider-registry.service.ts): `core/src/providers/provider-registry.service.ts`
- [Session store](https://github.com/robjvan/icos-v3/blob/master/core/src/conversation/session.store.ts): `core/src/conversation/session.store.ts`
- [SQLite sessions](https://github.com/robjvan/icos-v3/blob/master/core/src/session/sqlite-session.repository.ts): `core/src/session/sqlite-session.repository.ts`

### Other components

- **User**

## Connections

- User → Chat interface: sends message
- Chat interface → Core API client: submits chat
- Core API client → Conversation API: calls REST
- Conversation API → Conversation service: handles turn
- Conversation service → LLM client: requests completion
- LLM client → Provider registry: resolves provider (evidence: `core/src/llm/llm-client.providers.ts`)
- Conversation service → Session store: persists transcript
- Session store → SQLite sessions: stores sessions (evidence: `core/src/session/sqlite-session.repository.ts`)
- Conversation service → Memory recall: retrieves context
- Conversation service → Candidate extraction: extracts candidates
- Candidate extraction → Epistemic claims: supports knowledge
- Memory review UI → Core API client: requests review data
- Core API client → Human approvals: resolves approval
- Human approvals → Memory promotion: authorizes promotion (evidence: `core/src/approvals/approval.service.ts`)
- Memory promotion → Epistemic claims: updates beliefs
- Conversation service → Skills: uses capabilities
- Conversation service → Tool execution: executes tools
- Tool execution → MCP bridge: bridges external tools
- Conversation service → Clarification queue: queues questions
- Core API client → Authentication: authenticates requests
