# narcooo/inkos architecture

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

- Interactive diagram: https://gitdiagram.com/narcooo/inkos
- Repository: https://github.com/narcooo/inkos

## Overview

InkOS is an AI-assisted story-production workspace for long-form and short fiction, screenplays, interactive worlds, Play, and translation. Users enter through Studio, CLI/TUI, or the documented shared interaction command; the agent harness turns requests into confirmed capabilities and domain-specific production, then persists artifacts and state. The README documents shared harness behavior and major product branches. Source excerpts show Studio routing/API setup and selected server, state, and CLI calls; links for unsampled domain implementations are documented or left unasserted.

Main entry points: [`packages/core/src/harness/runtime.ts`](https://github.com/narcooo/inkos/blob/master/packages/core/src/harness/runtime.ts) (Production harness), [`packages/studio/src/hooks/use-api.ts`](https://github.com/narcooo/inkos/blob/master/packages/studio/src/hooks/use-api.ts) (Studio API client), [`packages/studio/src/App.tsx`](https://github.com/narcooo/inkos/blob/master/packages/studio/src/App.tsx) (Studio workspace), [`packages/studio/src/api/server.ts`](https://github.com/narcooo/inkos/blob/master/packages/studio/src/api/server.ts) (Studio API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_studio["Studio workspace<br/>[App.tsx]"]
  node_studio_chat["Chat and creation<br/>[ChatPage.tsx]"]
  node_studio_api["Studio API<br/>[server.ts]"]
  node_studio_settings["Studio settings"]
  node_studio_translation["Translation manager"]
  node_studio_import["Import manager<br/>[ImportManager.tsx]"]
  node_studio_style["Style manager<br/>[StyleManager.tsx]"]
  node_cli["CLI commands<br/>[program.ts]"]
  node_tui["Terminal workspace<br/>[app.ts]"]
  node_cli_localization["CLI localization<br/>[localization.ts]"]
  node_studio_api_client["Studio API client<br/>[use-api.ts]"]
  node_studio_theme["Studio theme<br/>[use-theme.ts]"]
  node_studio_language["Studio language<br/>[app-language.ts]"]
  node_service_detail["Service configuration"]
end

subgraph group_runtime["Agent runtime"]
  node_harness["Production harness<br/>[runtime.ts]"]
  node_worker["Agent worker<br/>[worker-agent.ts]"]
  node_skills["Skills and profiles<br/>[registry.ts]"]
  node_llm["Model providers<br/>[provider.ts]"]
end

subgraph group_production["Creative production"]
  node_longform["Long-form writing<br/>[runner.ts]"]
  node_short_screen["Short and screen"]
  node_interactive["Interactive film<br/>[generate.ts]"]
  node_play["Play worlds<br/>[play-runner.ts]"]
  node_translation["Translation production<br/>[translation.ts]"]
  node_forecast["Narrative forecasting<br/>[runner.ts]"]
end

subgraph group_foundation["State and services"]
  node_state[("Project state<br/>[manager.ts]")]
  node_chapter_edit["Chapter workspace<br/>[edit-controller.ts]"]
  node_atomic["Atomic persistence<br/>[atomic-file-set.ts]"]
  node_materials["Materials retrieval<br/>[retrieve.ts]"]
end

node_studio_user(("Studio user"))
node_cli_user(("CLI/TUI user"))

node_studio_user -->|"uses"| node_studio
node_cli_user -->|"runs"| node_cli
node_cli_user -->|"uses"| node_tui
node_studio -->|"routes to"| node_studio_chat
node_studio_chat -.->|"requests data"| node_studio_api_client
node_studio_api_client -->|"calls HTTP API"| node_studio_api
node_studio_settings -->|"uses"| node_studio_api_client
node_studio_translation -->|"requests data"| node_studio_api_client
node_studio_import -->|"submits imports"| node_studio_api_client
node_studio_style -->|"submits style"| node_studio_api_client
node_studio_api -->|"executes capabilities"| node_harness
node_studio_api -->|"runs revision"| node_longform
node_cli -->|"shares interaction"| node_harness
node_tui -->|"shares agent core"| node_harness
node_harness -->|"runs agent"| node_worker
node_harness -->|"activates skills"| node_skills
node_worker -->|"requests completion"| node_llm
node_harness -->|"dispatches actions"| node_longform
node_harness -->|"dispatches actions"| node_short_screen
node_harness -->|"dispatches actions"| node_interactive
node_harness -->|"dispatches actions"| node_play
node_harness -->|"dispatches actions"| node_translation
node_harness -->|"dispatches actions"| node_forecast
node_longform -.->|"updates state"| node_state
node_chapter_edit -->|"validates edits"| node_state
node_state -->|"commits files"| node_atomic
node_materials -.->|"supplies context"| node_harness
node_studio -->|"selects theme"| node_studio_theme
node_studio -->|"sets language"| node_studio_language

click node_studio "https://github.com/narcooo/inkos/blob/master/packages/studio/src/App.tsx"
click node_studio_chat "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ChatPage.tsx"
click node_studio_api "https://github.com/narcooo/inkos/blob/master/packages/studio/src/api/server.ts"
click node_studio_settings "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ProjectSettings.tsx"
click node_studio_translation "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/TranslationManager.tsx"
click node_studio_import "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ImportManager.tsx"
click node_studio_style "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/StyleManager.tsx"
click node_cli "https://github.com/narcooo/inkos/blob/master/packages/cli/src/program.ts"
click node_tui "https://github.com/narcooo/inkos/blob/master/packages/cli/src/tui/app.ts"
click node_harness "https://github.com/narcooo/inkos/blob/master/packages/core/src/harness/runtime.ts"
click node_worker "https://github.com/narcooo/inkos/blob/master/packages/core/src/agent/worker-agent.ts"
click node_skills "https://github.com/narcooo/inkos/blob/master/packages/core/src/skills/registry.ts"
click node_llm "https://github.com/narcooo/inkos/blob/master/packages/core/src/llm/provider.ts"
click node_longform "https://github.com/narcooo/inkos/blob/master/packages/core/src/pipeline/runner.ts"
click node_short_screen "https://github.com/narcooo/inkos/blob/master/packages/core/src/pipeline/short-fiction-runner.ts"
click node_interactive "https://github.com/narcooo/inkos/blob/master/packages/core/src/interactive-film/generate.ts"
click node_play "https://github.com/narcooo/inkos/blob/master/packages/core/src/play/play-runner.ts"
click node_translation "https://github.com/narcooo/inkos/blob/master/packages/core/src/harness/tools/translation.ts"
click node_forecast "https://github.com/narcooo/inkos/blob/master/packages/core/src/forecast/runner.ts"
click node_state "https://github.com/narcooo/inkos/blob/master/packages/core/src/state/manager.ts"
click node_chapter_edit "https://github.com/narcooo/inkos/blob/master/packages/core/src/interaction/edit-controller.ts"
click node_atomic "https://github.com/narcooo/inkos/blob/master/packages/core/src/utils/atomic-file-set.ts"
click node_materials "https://github.com/narcooo/inkos/blob/master/packages/core/src/materials/retrieve.ts"
click node_cli_localization "https://github.com/narcooo/inkos/blob/master/packages/cli/src/localization.ts"
click node_studio_api_client "https://github.com/narcooo/inkos/blob/master/packages/studio/src/hooks/use-api.ts"
click node_studio_theme "https://github.com/narcooo/inkos/blob/master/packages/studio/src/hooks/use-theme.ts"
click node_studio_language "https://github.com/narcooo/inkos/blob/master/packages/studio/src/lib/app-language.ts"
click node_service_detail "https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ServiceDetailPage.tsx"

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_studio,node_studio_chat,node_studio_api,node_studio_settings,node_studio_translation,node_studio_import,node_studio_style,node_cli,node_tui,node_cli_localization,node_studio_api_client,node_studio_theme,node_studio_language,node_service_detail,node_studio_user,node_cli_user toneBlue
class node_harness,node_worker,node_skills,node_llm toneAmber
class node_longform,node_short_screen,node_interactive,node_play,node_translation,node_forecast toneMint
class node_state,node_chapter_edit,node_atomic,node_materials toneRose
```

## Components

### User interfaces

- [Studio workspace](https://github.com/narcooo/inkos/blob/master/packages/studio/src/App.tsx): `packages/studio/src/App.tsx`
- [Chat and creation](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ChatPage.tsx): `packages/studio/src/pages/ChatPage.tsx`
- [Studio API](https://github.com/narcooo/inkos/blob/master/packages/studio/src/api/server.ts): `packages/studio/src/api/server.ts`
- [Studio settings](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ProjectSettings.tsx): `packages/studio/src/pages/ProjectSettings.tsx`
- [Translation manager](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/TranslationManager.tsx): `packages/studio/src/pages/TranslationManager.tsx`
- [Import manager](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ImportManager.tsx): `packages/studio/src/pages/ImportManager.tsx`
- [Style manager](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/StyleManager.tsx): `packages/studio/src/pages/StyleManager.tsx`
- [CLI commands](https://github.com/narcooo/inkos/blob/master/packages/cli/src/program.ts): `packages/cli/src/program.ts`
- [Terminal workspace](https://github.com/narcooo/inkos/blob/master/packages/cli/src/tui/app.ts): `packages/cli/src/tui/app.ts`
- [CLI localization](https://github.com/narcooo/inkos/blob/master/packages/cli/src/localization.ts): `packages/cli/src/localization.ts`
- [Studio API client](https://github.com/narcooo/inkos/blob/master/packages/studio/src/hooks/use-api.ts): `packages/studio/src/hooks/use-api.ts`
- [Studio theme](https://github.com/narcooo/inkos/blob/master/packages/studio/src/hooks/use-theme.ts): `packages/studio/src/hooks/use-theme.ts`
- [Studio language](https://github.com/narcooo/inkos/blob/master/packages/studio/src/lib/app-language.ts): `packages/studio/src/lib/app-language.ts`
- [Service configuration](https://github.com/narcooo/inkos/blob/master/packages/studio/src/pages/ServiceDetailPage.tsx): `packages/studio/src/pages/ServiceDetailPage.tsx`

### Agent runtime

- [Production harness](https://github.com/narcooo/inkos/blob/master/packages/core/src/harness/runtime.ts): `packages/core/src/harness/runtime.ts`
- [Agent worker](https://github.com/narcooo/inkos/blob/master/packages/core/src/agent/worker-agent.ts): `packages/core/src/agent/worker-agent.ts`
- [Skills and profiles](https://github.com/narcooo/inkos/blob/master/packages/core/src/skills/registry.ts): `packages/core/src/skills/registry.ts`
- [Model providers](https://github.com/narcooo/inkos/blob/master/packages/core/src/llm/provider.ts): `packages/core/src/llm/provider.ts`

### Creative production

- [Long-form writing](https://github.com/narcooo/inkos/blob/master/packages/core/src/pipeline/runner.ts): `packages/core/src/pipeline/runner.ts`
- [Short and screen](https://github.com/narcooo/inkos/blob/master/packages/core/src/pipeline/short-fiction-runner.ts): `packages/core/src/pipeline/short-fiction-runner.ts`
- [Interactive film](https://github.com/narcooo/inkos/blob/master/packages/core/src/interactive-film/generate.ts): `packages/core/src/interactive-film/generate.ts`
- [Play worlds](https://github.com/narcooo/inkos/blob/master/packages/core/src/play/play-runner.ts): `packages/core/src/play/play-runner.ts`
- [Translation production](https://github.com/narcooo/inkos/blob/master/packages/core/src/harness/tools/translation.ts): `packages/core/src/harness/tools/translation.ts`
- [Narrative forecasting](https://github.com/narcooo/inkos/blob/master/packages/core/src/forecast/runner.ts): `packages/core/src/forecast/runner.ts`

### State and services

- [Project state](https://github.com/narcooo/inkos/blob/master/packages/core/src/state/manager.ts): `packages/core/src/state/manager.ts`
- [Chapter workspace](https://github.com/narcooo/inkos/blob/master/packages/core/src/interaction/edit-controller.ts): `packages/core/src/interaction/edit-controller.ts`
- [Atomic persistence](https://github.com/narcooo/inkos/blob/master/packages/core/src/utils/atomic-file-set.ts): `packages/core/src/utils/atomic-file-set.ts`
- [Materials retrieval](https://github.com/narcooo/inkos/blob/master/packages/core/src/materials/retrieve.ts): `packages/core/src/materials/retrieve.ts`

### Other components

- **Studio user**
- **CLI/TUI user**

## Connections

- Studio user → Studio workspace: uses
- CLI/TUI user → CLI commands: runs
- CLI/TUI user → Terminal workspace: uses
- Studio workspace → Chat and creation: routes to (evidence: `packages/studio/src/App.tsx`)
- Chat and creation → Studio API client: requests data
- Studio API client → Studio API: calls HTTP API
- Studio settings → Studio API client: uses
- Translation manager → Studio API client: requests data (evidence: `packages/studio/src/pages/TranslationManager.tsx`)
- Import manager → Studio API client: submits imports (evidence: `packages/studio/src/pages/ImportManager.tsx`)
- Style manager → Studio API client: submits style (evidence: `packages/studio/src/pages/StyleManager.tsx`)
- Studio API → Production harness: executes capabilities (evidence: `packages/studio/src/api/server.ts`)
- Studio API → Long-form writing: runs revision (evidence: `packages/studio/src/api/server.ts`)
- CLI commands → Production harness: shares interaction
- Terminal workspace → Production harness: shares agent core
- Production harness → Agent worker: runs agent
- Production harness → Skills and profiles: activates skills
- Agent worker → Model providers: requests completion (evidence: `packages/core/src/agent/worker-agent.ts`)
- Production harness → Long-form writing: dispatches actions
- Production harness → Short and screen: dispatches actions
- Production harness → Interactive film: dispatches actions
- Production harness → Play worlds: dispatches actions
- Production harness → Translation production: dispatches actions
- Production harness → Narrative forecasting: dispatches actions
- Long-form writing → Project state: updates state
- Chapter workspace → Project state: validates edits (evidence: `packages/core/src/interaction/edit-controller.ts`)
- Project state → Atomic persistence: commits files (evidence: `packages/core/src/state/manager.ts`)
- Materials retrieval → Production harness: supplies context
- Studio workspace → Studio theme: selects theme (evidence: `packages/studio/src/App.tsx`)
- Studio workspace → Studio language: sets language (evidence: `packages/studio/src/App.tsx`)
