# amierlorenz/articulate architecture

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

- Interactive diagram: https://gitdiagram.com/amierlorenz/articulate
- Repository: https://github.com/amierlorenz/articulate

## Overview

Articulate is a personal academic-workflow application: it gathers course material and recordings, turns eligible inputs into notes and tasks, and writes durable results to a user vault. The main execution framework is a resumable source-to-item pipeline, run by named jobs; domain steps handle Canvas intake, Pocket polling, inbox notes, task extraction, and library matching. Calendar matching and citation processing support course context and knowledge enrichment. The excerpts and source index establish several calls and shared stores, but README content is absent and some integrations are unsampled, so uncertain links are omitted.

Main entry points: [`src/articulate/core/db.py`](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/db.py) (SQLite state), [`src/articulate/core/pipeline.py`](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/pipeline.py) (Item pipeline), [`src/articulate/core/models/runner.py`](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/models/runner.py) (Model runner), [`src/articulate/core/vault.py`](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/vault.py) (Vault writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_jobs["Job runner<br/>[jobs.py]"]
  node_pipeline["Item pipeline<br/>[pipeline.py]"]
  node_registry["Step registry<br/>[registry.py]"]
end

subgraph group_intake["Source intake"]
  node_canvas["Canvas intake<br/>[pick.py]"]
  node_canvas_exam["Exam intake<br/>[exams.py]"]
  node_pocket["Pocket polling<br/>[source.py]"]
  node_calendar["Calendar matching<br/>[match.py]"]
end

subgraph group_knowledge["Knowledge processing"]
  node_inbox["Inbox notes<br/>[step.py]"]
  node_transcript["Transcript reader<br/>[transcript.py]"]
  node_extract["Task extraction<br/>[extract.py]"]
  node_task_send["Task delivery<br/>[send.py]"]
  node_citation["Citation intake<br/>[__init__.py]"]
  node_library["Library matching<br/>[__init__.py]"]
end

subgraph group_runtime["Models and runtime"]
  node_models["Model runner<br/>[runner.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_handoff["Handoff schemas<br/>[imports.py]"]
end

subgraph group_state["State and output"]
  node_database[("SQLite state<br/>[db.py]")]
  node_taskqueue["Task queue<br/>[taskqueue.py]"]
  node_flags["Flags and holds<br/>[flags.py]"]
  node_vault["Vault writer<br/>[vault.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_runlog["Run log<br/>[runlog.py]"]
  node_paths["Path resolution<br/>[paths.py]"]
  node_ids["ID helpers<br/>[ids.py]"]
end

node_operator(("Operator / scheduler"))

node_operator -.->|"starts jobs"| node_jobs
node_jobs -->|"records runs"| node_database
node_jobs -->|"runs steps"| node_pipeline
node_registry -->|"registers steps"| node_jobs
node_canvas -->|"emits items"| node_pipeline
node_canvas -->|"uses exam intake"| node_canvas_exam
node_pocket -->|"matches events"| node_calendar
node_pocket -->|"emits items"| node_pipeline
node_inbox -->|"matches meetings"| node_calendar
node_inbox -->|"requests inference"| node_models
node_inbox -->|"reads and writes"| node_database
node_inbox -->|"writes notes"| node_vault
node_extract -->|"reads transcripts"| node_transcript
node_extract -->|"requests inference"| node_models
node_extract -->|"records extraction"| node_database
node_task_send -->|"loads task state"| node_database
node_task_send -->|"uses pipeline"| node_pipeline
node_citation -->|"requests inference"| node_models
node_citation -->|"stores citation state"| node_database
node_library -->|"judges matches"| node_models
node_library -->|"uses pipeline"| node_pipeline
node_models -->|"loads model settings"| node_config
node_models -->|"tracks usage"| node_database
node_pipeline -->|"persists item state"| node_database
node_pipeline -->|"creates identifiers"| node_ids
node_flags -->|"stores flags"| node_database
node_flags -->|"holds items"| node_pipeline
node_flags -->|"uses task queue"| node_taskqueue
node_health -->|"checks state"| node_database
node_health -->|"checks vault"| node_vault
node_health -->|"checks run log"| node_runlog
node_taskqueue -->|"persists queue"| node_database
node_runlog -->|"uses vault"| node_vault
node_paths -->|"resolves config paths"| node_config
node_database -->|"resolves database path"| node_paths
node_vault -->|"records notes"| node_database
node_vault -->|"generates identifiers"| node_ids
node_handoff -.->|"defines import state"| node_database

click node_jobs "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/jobs.py"
click node_pipeline "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/pipeline.py"
click node_registry "https://github.com/amierlorenz/articulate/blob/main/src/articulate/registry.py"
click node_canvas "https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/canvas/pick.py"
click node_canvas_exam "https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/canvas/exams.py"
click node_pocket "https://github.com/amierlorenz/articulate/blob/main/src/articulate/pocket/source.py"
click node_calendar "https://github.com/amierlorenz/articulate/blob/main/src/articulate/calendar/match.py"
click node_inbox "https://github.com/amierlorenz/articulate/blob/main/src/articulate/inbox/step.py"
click node_transcript "https://github.com/amierlorenz/articulate/blob/main/src/articulate/inbox/transcript.py"
click node_extract "https://github.com/amierlorenz/articulate/blob/main/src/articulate/tasks/extract.py"
click node_task_send "https://github.com/amierlorenz/articulate/blob/main/src/articulate/tasks/send.py"
click node_citation "https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/cite/__init__.py"
click node_library "https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/library/__init__.py"
click node_models "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/models/runner.py"
click node_config "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/config.py"
click node_handoff "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/handoff_schemas/imports.py"
click node_database "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/db.py"
click node_taskqueue "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/taskqueue.py"
click node_flags "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/flags.py"
click node_vault "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/vault.py"
click node_health "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/health.py"
click node_runlog "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/runlog.py"
click node_paths "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/paths.py"
click node_ids "https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/ids.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_jobs,node_pipeline,node_registry toneBlue
class node_canvas,node_canvas_exam,node_pocket,node_calendar toneAmber
class node_inbox,node_transcript,node_extract,node_task_send,node_citation,node_library toneMint
class node_models,node_config,node_handoff,node_operator toneRose
class node_database,node_taskqueue,node_flags,node_vault,node_health,node_runlog,node_paths,node_ids toneIndigo
```

## Components

### Run orchestration

- [Job runner](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/jobs.py): `src/articulate/core/jobs.py`
- [Item pipeline](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/pipeline.py): `src/articulate/core/pipeline.py`
- [Step registry](https://github.com/amierlorenz/articulate/blob/main/src/articulate/registry.py): `src/articulate/registry.py`

### Source intake

- [Canvas intake](https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/canvas/pick.py): `src/articulate/intake/canvas/pick.py`
- [Exam intake](https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/canvas/exams.py): `src/articulate/intake/canvas/exams.py`
- [Pocket polling](https://github.com/amierlorenz/articulate/blob/main/src/articulate/pocket/source.py): `src/articulate/pocket/source.py`
- [Calendar matching](https://github.com/amierlorenz/articulate/blob/main/src/articulate/calendar/match.py): `src/articulate/calendar/match.py`

### Knowledge processing

- [Inbox notes](https://github.com/amierlorenz/articulate/blob/main/src/articulate/inbox/step.py): `src/articulate/inbox/step.py`
- [Transcript reader](https://github.com/amierlorenz/articulate/blob/main/src/articulate/inbox/transcript.py): `src/articulate/inbox/transcript.py`
- [Task extraction](https://github.com/amierlorenz/articulate/blob/main/src/articulate/tasks/extract.py): `src/articulate/tasks/extract.py`
- [Task delivery](https://github.com/amierlorenz/articulate/blob/main/src/articulate/tasks/send.py): `src/articulate/tasks/send.py`
- [Citation intake](https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/cite/__init__.py): `src/articulate/intake/cite/__init__.py`
- [Library matching](https://github.com/amierlorenz/articulate/blob/main/src/articulate/intake/library/__init__.py): `src/articulate/intake/library/__init__.py`

### Models and runtime

- [Model runner](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/models/runner.py): `src/articulate/core/models/runner.py`
- [Configuration](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/config.py): `src/articulate/core/config.py`
- [Handoff schemas](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/handoff_schemas/imports.py): `src/articulate/core/handoff_schemas/imports.py`

### State and output

- [SQLite state](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/db.py): `src/articulate/core/db.py`
- [Task queue](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/taskqueue.py): `src/articulate/core/taskqueue.py`
- [Flags and holds](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/flags.py): `src/articulate/core/flags.py`
- [Vault writer](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/vault.py): `src/articulate/core/vault.py`
- [Health checks](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/health.py): `src/articulate/core/health.py`
- [Run log](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/runlog.py): `src/articulate/core/runlog.py`
- [Path resolution](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/paths.py): `src/articulate/core/paths.py`
- [ID helpers](https://github.com/amierlorenz/articulate/blob/main/src/articulate/core/ids.py): `src/articulate/core/ids.py`

### Other components

- **Operator / scheduler**

## Connections

- Operator / scheduler → Job runner: starts jobs
- Job runner → SQLite state: records runs (evidence: `src/articulate/core/jobs.py`)
- Job runner → Item pipeline: runs steps (evidence: `src/articulate/core/jobs.py`)
- Step registry → Job runner: registers steps (evidence: `src/articulate/registry.py`)
- Canvas intake → Item pipeline: emits items (evidence: `src/articulate/intake/canvas/pick.py`)
- Canvas intake → Exam intake: uses exam intake (evidence: `src/articulate/intake/canvas/pick.py`)
- Pocket polling → Calendar matching: matches events (evidence: `src/articulate/pocket/source.py`)
- Pocket polling → Item pipeline: emits items (evidence: `src/articulate/pocket/source.py`)
- Inbox notes → Calendar matching: matches meetings (evidence: `src/articulate/inbox/step.py`)
- Inbox notes → Model runner: requests inference (evidence: `src/articulate/inbox/step.py`)
- Inbox notes → SQLite state: reads and writes (evidence: `src/articulate/inbox/step.py`)
- Inbox notes → Vault writer: writes notes (evidence: `src/articulate/inbox/step.py`)
- Task extraction → Transcript reader: reads transcripts (evidence: `src/articulate/tasks/extract.py`)
- Task extraction → Model runner: requests inference (evidence: `src/articulate/tasks/extract.py`)
- Task extraction → SQLite state: records extraction (evidence: `src/articulate/tasks/extract.py`)
- Task delivery → SQLite state: loads task state (evidence: `src/articulate/tasks/send.py`)
- Task delivery → Item pipeline: uses pipeline (evidence: `src/articulate/tasks/send.py`)
- Citation intake → Model runner: requests inference (evidence: `src/articulate/intake/cite/__init__.py`)
- Citation intake → SQLite state: stores citation state (evidence: `src/articulate/intake/cite/__init__.py`)
- Library matching → Model runner: judges matches (evidence: `src/articulate/intake/library/__init__.py`)
- Library matching → Item pipeline: uses pipeline (evidence: `src/articulate/intake/library/__init__.py`)
- Model runner → Configuration: loads model settings (evidence: `src/articulate/core/models/runner.py`)
- Model runner → SQLite state: tracks usage (evidence: `src/articulate/core/models/runner.py`)
- Item pipeline → SQLite state: persists item state (evidence: `src/articulate/core/pipeline.py`)
- Item pipeline → ID helpers: creates identifiers (evidence: `src/articulate/core/pipeline.py`)
- Flags and holds → SQLite state: stores flags (evidence: `src/articulate/core/flags.py`)
- Flags and holds → Item pipeline: holds items (evidence: `src/articulate/core/flags.py`)
- Flags and holds → Task queue: uses task queue (evidence: `src/articulate/core/flags.py`)
- Health checks → SQLite state: checks state (evidence: `src/articulate/core/health.py`)
- Health checks → Vault writer: checks vault (evidence: `src/articulate/core/health.py`)
- Health checks → Run log: checks run log (evidence: `src/articulate/core/health.py`)
- Task queue → SQLite state: persists queue (evidence: `src/articulate/core/taskqueue.py`)
- Run log → Vault writer: uses vault (evidence: `src/articulate/core/runlog.py`)
- Path resolution → Configuration: resolves config paths (evidence: `src/articulate/core/paths.py`)
- SQLite state → Path resolution: resolves database path (evidence: `src/articulate/core/db.py`)
- Vault writer → SQLite state: records notes (evidence: `src/articulate/core/vault.py`)
- Vault writer → ID helpers: generates identifiers (evidence: `src/articulate/core/vault.py`)
- Handoff schemas → SQLite state: defines import state
