# kisera001/ki-co architecture

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

- Interactive diagram: https://gitdiagram.com/kisera001/ki-co
- Repository: https://github.com/kisera001/ki-co

## Overview

KI-CO is a local-first AI companion cottage: users configure a persona and model channels, chat, and carry context forward through memory, state cards, and diary records. The app also provides archive import and resurrection, a cinema companion room, memory and time galleries, settings, and backup. The excerpts show selected routing, storage, and service links; other capability links below are documented by the README, not inferred from unsampled implementation.

Main entry points: [`src/App.tsx`](https://github.com/kisera001/ki-co/blob/main/src/App.tsx) (App shell), [`src/components/chat/ChatPage.tsx`](https://github.com/kisera001/ki-co/blob/main/src/components/chat/ChatPage.tsx) (Long chat), [`src/components/MemoryGalleryPage.tsx`](https://github.com/kisera001/ki-co/blob/main/src/components/MemoryGalleryPage.tsx) (Memory Gallery), [`src/storage/memoryBank.ts`](https://github.com/kisera001/ki-co/blob/main/src/storage/memoryBank.ts) (Memory bank)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Cottage experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_bond["Bond Space<br/>[BondSpacePage.tsx]"]
  node_persona["Persona core"]
  node_gallery["Memory Gallery"]
  node_time["Time Corridor"]
end

subgraph group_conversation["Chat and context"]
  node_chat["Long chat<br/>[ChatPage.tsx]"]
  node_adapter["Companion adapters"]
  node_topicgate["Topic recall gate<br/>[topicMemoryGate.ts]"]
  node_recalljudge["Recall judge"]
  node_timeaware["Time awareness<br/>[timeAwareness.ts]"]
  node_session["State card"]
end

subgraph group_memory["Memory and history"]
  node_memory[("Memory bank<br/>[memoryBank.ts]")]
  node_chronicle["Diary service"]
  node_chronicles[("Diaries and seeds<br/>[chronicles.ts]")]
  node_archive_ui["Archive reader"]
  node_archive_parse["Archive parser<br/>[archiveParser.ts]"]
  node_archive_resurrect["Archive resurrection"]
  node_archive_db[("Archive store<br/>[archiveDb.ts]")]
end

subgraph group_cinema["Cinema room"]
  node_cinema["Cinema room"]
  node_watch[("Watch records<br/>[watchRecords.ts]")]
end

subgraph group_platform["Settings and storage"]
  node_conversations[("Conversations<br/>[conversations.ts]")]
  node_persona_store[("Persona profile<br/>[personaProfile.ts]")]
  node_settings[("Model settings<br/>[uplinkSettings.ts]")]
  node_backup["Full backup<br/>[fullBackup.ts]"]
end

node_user(("User"))
node_providers{{"Model providers"}}

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_bond
node_app -->|"routes to"| node_chat
node_app -->|"opens"| node_cinema
node_app -->|"routes to"| node_gallery
node_app -->|"routes to"| node_time
node_app -->|"routes to"| node_persona
node_app -->|"loads settings"| node_settings
node_app -->|"loads profile"| node_persona_store
node_app -->|"creates backup"| node_backup
node_chat -.->|"requests replies"| node_adapter
node_adapter -.->|"calls model"| node_providers
node_chat -->|"checks recall"| node_topicgate
node_chat -->|"judges ambiguity"| node_recalljudge
node_chat -->|"builds time context"| node_timeaware
node_chat -->|"updates state"| node_session
node_chat -->|"reads and saves"| node_conversations
node_chat -->|"retrieves memories"| node_memory
node_chat -->|"organizes diary"| node_chronicle
node_chronicle -->|"writes entries"| node_chronicles
node_memory -->|"reads history"| node_conversations
node_memory -->|"reads diaries"| node_chronicles
node_gallery -->|"parses imports"| node_archive_parse
node_gallery -->|"reads archives"| node_archive_db
node_gallery -->|"resumes history"| node_archive_resurrect
node_archive_parse -->|"stores records"| node_archive_db
node_archive_resurrect -->|"reads records"| node_archive_db
node_cinema -->|"saves progress"| node_watch
node_cinema -->|"stores room chat"| node_conversations
node_gallery -->|"manages diary"| node_chronicles
node_time -->|"generates summaries"| node_chronicle

click node_app "https://github.com/kisera001/ki-co/blob/main/src/App.tsx"
click node_bond "https://github.com/kisera001/ki-co/blob/main/src/components/BondSpacePage.tsx"
click node_persona "https://github.com/kisera001/ki-co/blob/main/src/components/PersonaCorePage.tsx"
click node_gallery "https://github.com/kisera001/ki-co/blob/main/src/components/MemoryGalleryPage.tsx"
click node_time "https://github.com/kisera001/ki-co/blob/main/src/components/TimeCorridorPage.tsx"
click node_chat "https://github.com/kisera001/ki-co/blob/main/src/components/chat/ChatPage.tsx"
click node_adapter "https://github.com/kisera001/ki-co/blob/main/src/adapters/companionAdapters.ts"
click node_topicgate "https://github.com/kisera001/ki-co/blob/main/src/utils/topicMemoryGate.ts"
click node_recalljudge "https://github.com/kisera001/ki-co/blob/main/src/services/topicRecallJudge.ts"
click node_timeaware "https://github.com/kisera001/ki-co/blob/main/src/utils/timeAwareness.ts"
click node_session "https://github.com/kisera001/ki-co/blob/main/src/services/sessionStateService.ts"
click node_conversations "https://github.com/kisera001/ki-co/blob/main/src/storage/conversations.ts"
click node_memory "https://github.com/kisera001/ki-co/blob/main/src/storage/memoryBank.ts"
click node_persona_store "https://github.com/kisera001/ki-co/blob/main/src/storage/personaProfile.ts"
click node_chronicle "https://github.com/kisera001/ki-co/blob/main/src/services/chronicleService.ts"
click node_chronicles "https://github.com/kisera001/ki-co/blob/main/src/storage/chronicles.ts"
click node_archive_ui "https://github.com/kisera001/ki-co/blob/main/src/components/MemoryGalleryPage.tsx"
click node_archive_parse "https://github.com/kisera001/ki-co/blob/main/src/services/archiveParser.ts"
click node_archive_resurrect "https://github.com/kisera001/ki-co/blob/main/src/services/archiveResurrectionService.ts"
click node_archive_db "https://github.com/kisera001/ki-co/blob/main/src/storage/archiveDb.ts"
click node_cinema "https://github.com/kisera001/ki-co/blob/main/src/components/CinemaCompanionRoom.tsx"
click node_watch "https://github.com/kisera001/ki-co/blob/main/src/storage/watchRecords.ts"
click node_settings "https://github.com/kisera001/ki-co/blob/main/src/settings/uplinkSettings.ts"
click node_backup "https://github.com/kisera001/ki-co/blob/main/src/storage/fullBackup.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_bond,node_persona,node_gallery,node_time,node_user toneBlue
class node_chat,node_adapter,node_topicgate,node_recalljudge,node_timeaware,node_session toneAmber
class node_memory,node_chronicle,node_chronicles,node_archive_ui,node_archive_parse,node_archive_resurrect,node_archive_db toneMint
class node_cinema,node_watch toneRose
class node_conversations,node_persona_store,node_settings,node_backup,node_providers toneIndigo
```

## Components

### Cottage experience

- [App shell](https://github.com/kisera001/ki-co/blob/main/src/App.tsx): `src/App.tsx`
- [Bond Space](https://github.com/kisera001/ki-co/blob/main/src/components/BondSpacePage.tsx): `src/components/BondSpacePage.tsx`
- [Persona core](https://github.com/kisera001/ki-co/blob/main/src/components/PersonaCorePage.tsx): `src/components/PersonaCorePage.tsx`
- [Memory Gallery](https://github.com/kisera001/ki-co/blob/main/src/components/MemoryGalleryPage.tsx): `src/components/MemoryGalleryPage.tsx`
- [Time Corridor](https://github.com/kisera001/ki-co/blob/main/src/components/TimeCorridorPage.tsx): `src/components/TimeCorridorPage.tsx`

### Chat and context

- [Long chat](https://github.com/kisera001/ki-co/blob/main/src/components/chat/ChatPage.tsx): `src/components/chat/ChatPage.tsx`
- [Companion adapters](https://github.com/kisera001/ki-co/blob/main/src/adapters/companionAdapters.ts): `src/adapters/companionAdapters.ts`
- [Topic recall gate](https://github.com/kisera001/ki-co/blob/main/src/utils/topicMemoryGate.ts): `src/utils/topicMemoryGate.ts`
- [Recall judge](https://github.com/kisera001/ki-co/blob/main/src/services/topicRecallJudge.ts): `src/services/topicRecallJudge.ts`
- [Time awareness](https://github.com/kisera001/ki-co/blob/main/src/utils/timeAwareness.ts): `src/utils/timeAwareness.ts`
- [State card](https://github.com/kisera001/ki-co/blob/main/src/services/sessionStateService.ts): `src/services/sessionStateService.ts`

### Memory and history

- [Memory bank](https://github.com/kisera001/ki-co/blob/main/src/storage/memoryBank.ts): `src/storage/memoryBank.ts`
- [Diary service](https://github.com/kisera001/ki-co/blob/main/src/services/chronicleService.ts): `src/services/chronicleService.ts`
- [Diaries and seeds](https://github.com/kisera001/ki-co/blob/main/src/storage/chronicles.ts): `src/storage/chronicles.ts`
- [Archive reader](https://github.com/kisera001/ki-co/blob/main/src/components/MemoryGalleryPage.tsx): `src/components/MemoryGalleryPage.tsx`
- [Archive parser](https://github.com/kisera001/ki-co/blob/main/src/services/archiveParser.ts): `src/services/archiveParser.ts`
- [Archive resurrection](https://github.com/kisera001/ki-co/blob/main/src/services/archiveResurrectionService.ts): `src/services/archiveResurrectionService.ts`
- [Archive store](https://github.com/kisera001/ki-co/blob/main/src/storage/archiveDb.ts): `src/storage/archiveDb.ts`

### Cinema room

- [Cinema room](https://github.com/kisera001/ki-co/blob/main/src/components/CinemaCompanionRoom.tsx): `src/components/CinemaCompanionRoom.tsx`
- [Watch records](https://github.com/kisera001/ki-co/blob/main/src/storage/watchRecords.ts): `src/storage/watchRecords.ts`

### Settings and storage

- [Conversations](https://github.com/kisera001/ki-co/blob/main/src/storage/conversations.ts): `src/storage/conversations.ts`
- [Persona profile](https://github.com/kisera001/ki-co/blob/main/src/storage/personaProfile.ts): `src/storage/personaProfile.ts`
- [Model settings](https://github.com/kisera001/ki-co/blob/main/src/settings/uplinkSettings.ts): `src/settings/uplinkSettings.ts`
- [Full backup](https://github.com/kisera001/ki-co/blob/main/src/storage/fullBackup.ts): `src/storage/fullBackup.ts`

### Other components

- **User**
- **Model providers**

## Connections

- User → App shell: uses (evidence: `README.md`)
- App shell → Bond Space: routes to (evidence: `src/App.tsx`)
- App shell → Long chat: routes to (evidence: `src/App.tsx`)
- App shell → Cinema room: opens (evidence: `src/App.tsx`)
- App shell → Memory Gallery: routes to (evidence: `src/App.tsx`)
- App shell → Time Corridor: routes to (evidence: `src/App.tsx`)
- App shell → Persona core: routes to (evidence: `src/App.tsx`)
- App shell → Model settings: loads settings (evidence: `src/App.tsx`)
- App shell → Persona profile: loads profile (evidence: `src/App.tsx`)
- App shell → Full backup: creates backup (evidence: `src/App.tsx`)
- Long chat → Companion adapters: requests replies
- Companion adapters → Model providers: calls model
- Long chat → Topic recall gate: checks recall (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → Recall judge: judges ambiguity (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → Time awareness: builds time context (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → State card: updates state (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → Conversations: reads and saves (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → Memory bank: retrieves memories (evidence: `src/components/chat/ChatPage.tsx`)
- Long chat → Diary service: organizes diary (evidence: `src/components/chat/ChatPage.tsx`)
- Diary service → Diaries and seeds: writes entries (evidence: `src/services/chronicleService.ts`)
- Memory bank → Conversations: reads history (evidence: `src/storage/memoryBank.ts`)
- Memory bank → Diaries and seeds: reads diaries (evidence: `src/storage/memoryBank.ts`)
- Memory Gallery → Archive parser: parses imports (evidence: `src/components/MemoryGalleryPage.tsx`)
- Memory Gallery → Archive store: reads archives (evidence: `src/components/MemoryGalleryPage.tsx`)
- Memory Gallery → Archive resurrection: resumes history (evidence: `src/components/MemoryGalleryPage.tsx`)
- Archive parser → Archive store: stores records (evidence: `src/services/archiveParser.ts`)
- Archive resurrection → Archive store: reads records (evidence: `src/services/archiveResurrectionService.ts`)
- Cinema room → Watch records: saves progress (evidence: `src/components/CinemaCompanionRoom.tsx`)
- Cinema room → Conversations: stores room chat (evidence: `src/components/CinemaCompanionRoom.tsx`)
- Memory Gallery → Diaries and seeds: manages diary (evidence: `src/components/MemoryGalleryPage.tsx`)
- Time Corridor → Diary service: generates summaries (evidence: `src/components/TimeCorridorPage.tsx`)