# n-huche/aos architecture

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

- Interactive diagram: https://gitdiagram.com/n-huche/aos
- Repository: https://github.com/n-huche/aos

## Overview

AOS is a Markdown-based personal operating system: users maintain tasks and projects in a private `user/` tree, then run commands to derive an index, close out daily activity, validate records, and keep checkbox-driven updates synchronized. Its runtime also builds monthly schedules and manages a watcher and calendar setup. The graph emphasizes documented commands and the source-indexed module relationships; several implementation excerpts are partial, so uncertain internal call chains are omitted.

Main entry points: [`scripts/aos_lib/cli.py`](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/cli.py) (Command dispatcher), [`scripts/aos_lib/daily.py`](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/daily.py) (Daily close), [`scripts/aos_lib/up.py`](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/up.py) (Runtime setup), [`scripts/aos_lib/watch.py`](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/watch.py) (Checkbox watcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Commands and operations"]
  node_cli["Command dispatcher<br/>[cli.py]"]
  node_setup["Runtime setup<br/>[up.py]"]
  node_watcher["Checkbox watcher<br/>[watch.py]"]
end

subgraph group_domain["Planning and daily workflow"]
  node_daily["Daily close<br/>[daily.py]"]
  node_index["Derived index<br/>[index.py]"]
  node_schedule["Monthly schedule<br/>[schedule.py]"]
  node_validate["Data validation<br/>[validate.py]"]
  node_reconcile["Task reconciliation<br/>[reconcile.py]"]
  node_sync["Checkbox sync<br/>[sync.py]"]
end

subgraph group_core["Task and data rules"]
  node_cadence["Cadence rules<br/>[cadence.py]"]
  node_taskio["Task file access<br/>[taskio.py]"]
  node_frontmatter["Markdown frontmatter<br/>[yamlfm.py]"]
  node_links["Task link rewriting<br/>[links.py]"]
  node_config["Paths and time<br/>[config.py]"]
end

subgraph group_state["User data and synchronization"]
  node_userfiles[("Private Markdown data")]
  node_git["Git synchronization<br/>[gitutil.py]"]
end

node_user(("AOS user"))
node_cron["Host cron"]

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches daily-close"| node_daily
node_cli -->|"dispatches reindex"| node_index
node_cli -->|"dispatches validate"| node_validate
node_cli -->|"dispatches watch"| node_watcher
node_cli -->|"dispatches up"| node_setup
node_setup -->|"catches up"| node_daily
node_setup -->|"installs calendar"| node_cron
node_setup -->|"starts if stopped"| node_watcher
node_daily -->|"reads and updates"| node_userfiles
node_index -->|"derives index"| node_userfiles
node_schedule -->|"writes month grids"| node_userfiles
node_validate -->|"checks records"| node_userfiles
node_watcher -->|"refreshes index"| node_index
node_watcher -->|"syncs changes"| node_git
node_daily -->|"uses sync operations"| node_sync
node_sync -->|"loads and saves"| node_taskio
node_reconcile -->|"moves task files"| node_taskio
node_taskio -->|"parses and writes"| node_frontmatter
node_cadence -->|"parses dates"| node_frontmatter
node_reconcile -->|"rewrites project links"| node_links
node_daily -->|"uses date rules"| node_cadence
node_cli -->|"resolves root"| node_config
node_taskio -->|"uses task paths"| node_config
node_git -->|"commits and pushes"| node_userfiles

click node_cli "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/cli.py"
click node_setup "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/up.py"
click node_watcher "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/watch.py"
click node_daily "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/daily.py"
click node_index "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/index.py"
click node_schedule "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/schedule.py"
click node_validate "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/validate.py"
click node_reconcile "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/reconcile.py"
click node_sync "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/sync.py"
click node_cadence "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/cadence.py"
click node_taskio "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/taskio.py"
click node_frontmatter "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/yamlfm.py"
click node_links "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/links.py"
click node_config "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/config.py"
click node_git "https://github.com/n-huche/aos/blob/main/scripts/aos_lib/gitutil.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_setup,node_watcher,node_user toneBlue
class node_daily,node_index,node_schedule,node_validate,node_reconcile,node_sync toneAmber
class node_cadence,node_taskio,node_frontmatter,node_links,node_config toneMint
class node_userfiles,node_git toneRose
class node_cron toneIndigo
```

## Components

### Commands and operations

- [Command dispatcher](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/cli.py): `scripts/aos_lib/cli.py`
- [Runtime setup](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/up.py): `scripts/aos_lib/up.py`
- [Checkbox watcher](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/watch.py): `scripts/aos_lib/watch.py`

### Planning and daily workflow

- [Daily close](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/daily.py): `scripts/aos_lib/daily.py`
- [Derived index](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/index.py): `scripts/aos_lib/index.py`
- [Monthly schedule](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/schedule.py): `scripts/aos_lib/schedule.py`
- [Data validation](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/validate.py): `scripts/aos_lib/validate.py`
- [Task reconciliation](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/reconcile.py): `scripts/aos_lib/reconcile.py`
- [Checkbox sync](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/sync.py): `scripts/aos_lib/sync.py`

### Task and data rules

- [Cadence rules](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/cadence.py): `scripts/aos_lib/cadence.py`
- [Task file access](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/taskio.py): `scripts/aos_lib/taskio.py`
- [Markdown frontmatter](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/yamlfm.py): `scripts/aos_lib/yamlfm.py`
- [Task link rewriting](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/links.py): `scripts/aos_lib/links.py`
- [Paths and time](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/config.py): `scripts/aos_lib/config.py`

### User data and synchronization

- **Private Markdown data**
- [Git synchronization](https://github.com/n-huche/aos/blob/main/scripts/aos_lib/gitutil.py): `scripts/aos_lib/gitutil.py`

### Other components

- **AOS user**
- **Host cron**

## Connections

- AOS user → Command dispatcher: runs commands (evidence: `README.md`)
- Command dispatcher → Daily close: dispatches daily-close (evidence: `scripts/aos_lib/cli.py`)
- Command dispatcher → Derived index: dispatches reindex (evidence: `scripts/aos_lib/cli.py`)
- Command dispatcher → Data validation: dispatches validate (evidence: `scripts/aos_lib/cli.py`)
- Command dispatcher → Checkbox watcher: dispatches watch (evidence: `scripts/aos_lib/cli.py`)
- Command dispatcher → Runtime setup: dispatches up (evidence: `scripts/aos_lib/cli.py`)
- Runtime setup → Daily close: catches up (evidence: `scripts/aos_lib/up.py`)
- Runtime setup → Host cron: installs calendar (evidence: `README.md`)
- Runtime setup → Checkbox watcher: starts if stopped (evidence: `README.md`)
- Daily close → Private Markdown data: reads and updates (evidence: `scripts/aos_lib/daily.py`)
- Derived index → Private Markdown data: derives index (evidence: `README.md`)
- Monthly schedule → Private Markdown data: writes month grids (evidence: `scripts/aos_lib/schedule.py`)
- Data validation → Private Markdown data: checks records (evidence: `README.md`)
- Checkbox watcher → Derived index: refreshes index (evidence: `scripts/aos_lib/watch.py`)
- Checkbox watcher → Git synchronization: syncs changes (evidence: `scripts/aos_lib/watch.py`)
- Daily close → Checkbox sync: uses sync operations (evidence: `scripts/aos_lib/daily.py`)
- Checkbox sync → Task file access: loads and saves (evidence: `scripts/aos_lib/sync.py`)
- Task reconciliation → Task file access: moves task files (evidence: `scripts/aos_lib/reconcile.py`)
- Task file access → Markdown frontmatter: parses and writes (evidence: `scripts/aos_lib/taskio.py`)
- Cadence rules → Markdown frontmatter: parses dates (evidence: `scripts/aos_lib/cadence.py`)
- Task reconciliation → Task link rewriting: rewrites project links (evidence: `scripts/aos_lib/reconcile.py`)
- Daily close → Cadence rules: uses date rules (evidence: `scripts/aos_lib/daily.py`)
- Command dispatcher → Paths and time: resolves root (evidence: `scripts/aos_lib/cli.py`)
- Task file access → Paths and time: uses task paths (evidence: `scripts/aos_lib/taskio.py`)
- Git synchronization → Private Markdown data: commits and pushes (evidence: `README.md`)
