# ebrahimabdelwahed/cardine architecture

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

- Interactive diagram: https://gitdiagram.com/ebrahimabdelwahed/cardine
- Repository: https://github.com/ebrahimabdelwahed/cardine

## Overview

Cardine is a repository-backed study workspace whose main workflow is to create a course, add trusted source material, and ask grounded questions through a conversation-first shell. Its runtime also supports durable sessions, generated and reviewed study artifacts, assessment, and recall. The README describes canonical events as authority and projections as rebuildable read models. The graph reflects those documented boundaries and sampled service behavior; unsampled subsystem wiring is shown only where the README explicitly establishes it.

Main entry points: [`src/study_agent/adapters/sqlite/event_store.py`](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/sqlite/event_store.py) (Canonical event stream), [`src/cardine/cli/main.py`](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/cli/main.py) (CLI host), [`src/cardine/application/indexing.py`](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/indexing.py) (Source indexing), [`src/study_agent/capabilities/gateway.py`](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/capabilities/gateway.py) (Study capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hosts["Product hosts"]
  node_cli["CLI host<br/>[main.py]"]
  node_shell["Conversation shell<br/>[product_shell.py]"]
  node_browser["Browser host<br/>[browser.py]"]
end

subgraph group_application["Application workflows"]
  node_turn["Conversation turns"]
  node_ask["Grounded ask<br/>[grounding_ask.py]"]
  node_indexing["Source indexing<br/>[indexing.py]"]
  node_admission["Document admission<br/>[admission.py]"]
end

subgraph group_learning["Learning runtime"]
  node_retrieval["Lesson retrieval"]
  node_playbooks["Study playbooks<br/>[engine.py]"]
  node_capabilities["Study capabilities<br/>[gateway.py]"]
  node_artifacts["Study artifacts<br/>[service.py]"]
  node_assessments["Assessment and grading<br/>[service.py]"]
  node_recall["Flashcard recall<br/>[service.py]"]
end

subgraph group_canonical["Canonical state"]
  node_sessions["Session turns<br/>[turn_service.py]"]
  node_event_store[("Canonical event stream<br/>[event_store.py]")]
  node_course_projection["Course read model<br/>[projection.py]"]
  node_blob_store[("Source snapshots<br/>[blob_store.py]")]
end

subgraph group_adapters["Adapters and integrations"]
  node_model["Model adapters<br/>[openai_luna.py]"]
  node_host_tools["Host tools<br/>[runner.py]"]
  node_repository["Repository boundary"]
end

node_learner(("Learner"))

node_learner -->|"runs commands"| node_cli
node_learner -->|"uses shell"| node_shell
node_learner -->|"uses browser"| node_browser
node_cli -->|"resolves repository"| node_repository
node_cli -->|"dispatches commands"| node_indexing
node_shell -->|"starts conversation"| node_turn
node_browser -->|"presents conversation"| node_turn
node_turn -->|"records turns"| node_sessions
node_indexing -->|"admits documents"| node_admission
node_indexing -->|"stores snapshots"| node_blob_store
node_ask -->|"selects evidence"| node_retrieval
node_ask -->|"runs study flow"| node_playbooks
node_playbooks -->|"dispatches capability"| node_capabilities
node_capabilities -.->|"requests generation"| node_model
node_capabilities -->|"invokes tools"| node_host_tools
node_sessions -->|"appends events"| node_event_store
node_artifacts -->|"appends events"| node_event_store
node_assessments -->|"appends events"| node_event_store
node_recall -->|"appends events"| node_event_store
node_course_projection -->|"projects events"| node_event_store

click node_cli "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/cli/main.py"
click node_shell "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/demo/product_shell.py"
click node_browser "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/demo/browser.py"
click node_turn "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/conversation_turn.py"
click node_ask "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/grounding_ask.py"
click node_indexing "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/indexing.py"
click node_admission "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/documents/admission.py"
click node_retrieval "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/knowledge/lesson_selection.py"
click node_playbooks "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/playbooks/engine.py"
click node_capabilities "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/capabilities/gateway.py"
click node_artifacts "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/artifacts/service.py"
click node_assessments "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/assessments/service.py"
click node_recall "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/recall/service.py"
click node_sessions "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/sessions/turn_service.py"
click node_event_store "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/sqlite/event_store.py"
click node_course_projection "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/courses/projection.py"
click node_blob_store "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/filesystem/blob_store.py"
click node_model "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/adapters/model/openai_luna.py"
click node_host_tools "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/hosts/runner.py"
click node_repository "https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/filesystem/repository_target.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_cli,node_shell,node_browser toneBlue
class node_turn,node_ask,node_indexing,node_admission toneAmber
class node_retrieval,node_playbooks,node_capabilities,node_artifacts,node_assessments,node_recall toneMint
class node_sessions,node_event_store,node_course_projection,node_blob_store toneRose
class node_model,node_host_tools,node_repository,node_learner toneIndigo
```

## Components

### Product hosts

- [CLI host](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/cli/main.py): `src/cardine/cli/main.py`
- [Conversation shell](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/demo/product_shell.py): `src/cardine/demo/product_shell.py`
- [Browser host](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/demo/browser.py): `src/cardine/demo/browser.py`

### Application workflows

- [Conversation turns](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/conversation_turn.py): `src/cardine/application/conversation_turn.py`
- [Grounded ask](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/grounding_ask.py): `src/cardine/application/grounding_ask.py`
- [Source indexing](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/application/indexing.py): `src/cardine/application/indexing.py`
- [Document admission](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/documents/admission.py): `src/cardine/documents/admission.py`

### Learning runtime

- [Lesson retrieval](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/knowledge/lesson_selection.py): `src/cardine/knowledge/lesson_selection.py`
- [Study playbooks](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/playbooks/engine.py): `src/study_agent/playbooks/engine.py`
- [Study capabilities](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/capabilities/gateway.py): `src/study_agent/capabilities/gateway.py`
- [Study artifacts](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/artifacts/service.py): `src/study_agent/artifacts/service.py`
- [Assessment and grading](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/assessments/service.py): `src/study_agent/assessments/service.py`
- [Flashcard recall](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/recall/service.py): `src/study_agent/recall/service.py`

### Canonical state

- [Session turns](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/sessions/turn_service.py): `src/study_agent/sessions/turn_service.py`
- [Canonical event stream](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/sqlite/event_store.py): `src/study_agent/adapters/sqlite/event_store.py`
- [Course read model](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/courses/projection.py): `src/cardine/courses/projection.py`
- [Source snapshots](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/filesystem/blob_store.py): `src/study_agent/adapters/filesystem/blob_store.py`

### Adapters and integrations

- [Model adapters](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/adapters/model/openai_luna.py): `src/cardine/adapters/model/openai_luna.py`
- [Host tools](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/cardine/hosts/runner.py): `src/cardine/hosts/runner.py`
- [Repository boundary](https://github.com/ebrahimabdelwahed/cardine/blob/main/src/study_agent/adapters/filesystem/repository_target.py): `src/study_agent/adapters/filesystem/repository_target.py`

### Other components

- **Learner**

## Connections

- Learner → CLI host: runs commands
- Learner → Conversation shell: uses shell
- Learner → Browser host: uses browser
- CLI host → Repository boundary: resolves repository
- CLI host → Source indexing: dispatches commands
- Conversation shell → Conversation turns: starts conversation
- Browser host → Conversation turns: presents conversation
- Conversation turns → Session turns: records turns
- Source indexing → Document admission: admits documents
- Source indexing → Source snapshots: stores snapshots
- Grounded ask → Lesson retrieval: selects evidence
- Grounded ask → Study playbooks: runs study flow
- Study playbooks → Study capabilities: dispatches capability
- Study capabilities → Model adapters: requests generation
- Study capabilities → Host tools: invokes tools
- Session turns → Canonical event stream: appends events
- Study artifacts → Canonical event stream: appends events
- Assessment and grading → Canonical event stream: appends events
- Flashcard recall → Canonical event stream: appends events
- Course read model → Canonical event stream: projects events