# razaele0003/pacana architecture

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

- Interactive diagram: https://gitdiagram.com/razaele0003/pacana
- Repository: https://github.com/razaele0003/pacana

## Overview

Pacana is a local-first focus timer and time journal, with an interactive capybara companion, available as a web app and a Windows desktop app. The main workflow enters the app, operates the timer and journal in the Pacana workspace, and persists state locally; the engine handles timer and checkpoint reconciliation, with schedule utilities supporting clock-aligned runs. The README documents progress/XP, photo reflections, backups, ringtones, fullscreen mode, and offline use. Some feature branches are represented by their documented UI or subsystem; desktop wiring and unsampled implementation details are not inferred.

Main entry points: [`components/pacana.tsx`](https://github.com/razaele0003/pacana/blob/main/components/pacana.tsx) (Pacana workspace), [`core/model.ts`](https://github.com/razaele0003/pacana/blob/main/core/model.ts) (App state model), [`lib/capy-npc/autonomous-controller.ts`](https://github.com/razaele0003/pacana/blob/main/lib/capy-npc/autonomous-controller.ts) (Autonomous behavior), [`core/engine.ts`](https://github.com/razaele0003/pacana/blob/main/core/engine.ts) (Focus engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App entry"]
  node_web_entry["Web entry<br/>[page.tsx]"]
  node_landing["Landing page<br/>[landing.tsx]"]
  node_app_entry["Workspace entry<br/>[page.tsx]"]
  node_desktop["Windows app<br/>[main.cjs]"]
end

subgraph group_workspace["Focus workspace"]
  node_pacana["Pacana workspace<br/>[pacana.tsx]"]
  node_engine["Focus engine<br/>[engine.ts]"]
  node_schedule["Clock scheduling<br/>[schedule.ts]"]
  node_model["App state model<br/>[model.ts]"]
  node_fullscreen["Fullscreen timer"]
  node_journal_photo["Journal photos<br/>[log-photo.tsx]"]
  node_ringtone_ui["Ringtone browser"]
end

subgraph group_companion["Cappy companion"]
  node_companion_ui["Interactive companion"]
  node_npc["Autonomous behavior"]
  node_obstacles["Movement geometry"]
  node_sprite["Capybara sprite<br/>[capy-sprite.tsx]"]
  node_sound["Companion sounds<br/>[companion-sound.ts]"]
end

subgraph group_local["Local services"]
  node_store[("Local state store<br/>[store.ts]")]
  node_backup["Backup validation<br/>[backup.ts]"]
  node_browser_audio["Browser audio<br/>[browser.ts]"]
  node_tones["Ringtone definitions<br/>[ringtones.ts]"]
end

node_person(("User"))

node_person -->|"opens"| node_web_entry
node_web_entry -->|"renders"| node_landing
node_person -->|"opens"| node_app_entry
node_app_entry -->|"renders"| node_pacana
node_pacana -->|"reconciles state"| node_engine
node_pacana -->|"gets day key"| node_schedule
node_pacana -->|"transacts state"| node_store
node_pacana -->|"unlocks audio"| node_browser_audio
node_pacana -->|"renders"| node_fullscreen
node_pacana -->|"renders"| node_companion_ui
node_pacana -->|"renders"| node_ringtone_ui
node_pacana -->|"uses"| node_journal_photo
node_engine -->|"gets next clock"| node_schedule
node_engine -->|"uses state types"| node_model
node_store -->|"stores state"| node_model
node_store -->|"uses validation"| node_backup
node_backup -->|"validates state"| node_model
node_browser_audio -->|"uses settings"| node_model
node_browser_audio -->|"plays definitions"| node_tones
node_ringtone_ui -->|"uses ringtone types"| node_model
node_ringtone_ui -->|"shows choices"| node_tones
node_companion_ui -->|"controls behavior"| node_npc
node_companion_ui -->|"renders"| node_sprite
node_npc -->|"uses poses"| node_sprite
node_npc -->|"plays cues"| node_sound
node_npc -->|"uses geometry"| node_obstacles

click node_web_entry "https://github.com/razaele0003/pacana/blob/main/app/page.tsx"
click node_landing "https://github.com/razaele0003/pacana/blob/main/components/landing.tsx"
click node_app_entry "https://github.com/razaele0003/pacana/blob/main/app/app/page.tsx"
click node_desktop "https://github.com/razaele0003/pacana/blob/main/desktop/main.cjs"
click node_pacana "https://github.com/razaele0003/pacana/blob/main/components/pacana.tsx"
click node_engine "https://github.com/razaele0003/pacana/blob/main/core/engine.ts"
click node_schedule "https://github.com/razaele0003/pacana/blob/main/core/schedule.ts"
click node_model "https://github.com/razaele0003/pacana/blob/main/core/model.ts"
click node_fullscreen "https://github.com/razaele0003/pacana/blob/main/components/fullscreen-timer.tsx"
click node_journal_photo "https://github.com/razaele0003/pacana/blob/main/components/log-photo.tsx"
click node_ringtone_ui "https://github.com/razaele0003/pacana/blob/main/components/ringtone-browser.tsx"
click node_companion_ui "https://github.com/razaele0003/pacana/blob/main/components/interactive-companion.tsx"
click node_npc "https://github.com/razaele0003/pacana/blob/main/lib/capy-npc/autonomous-controller.ts"
click node_obstacles "https://github.com/razaele0003/pacana/blob/main/lib/capy-npc/obstacle-manager.ts"
click node_sprite "https://github.com/razaele0003/pacana/blob/main/components/capy-sprite.tsx"
click node_sound "https://github.com/razaele0003/pacana/blob/main/lib/companion-sound.ts"
click node_store "https://github.com/razaele0003/pacana/blob/main/data/store.ts"
click node_backup "https://github.com/razaele0003/pacana/blob/main/data/backup.ts"
click node_browser_audio "https://github.com/razaele0003/pacana/blob/main/adapters/browser.ts"
click node_tones "https://github.com/razaele0003/pacana/blob/main/core/ringtones.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_web_entry,node_landing,node_app_entry,node_desktop,node_person toneBlue
class node_pacana,node_engine,node_schedule,node_model,node_fullscreen,node_journal_photo,node_ringtone_ui toneAmber
class node_companion_ui,node_npc,node_obstacles,node_sprite,node_sound toneMint
class node_store,node_backup,node_browser_audio,node_tones toneRose
```

## Components

### App entry

- [Web entry](https://github.com/razaele0003/pacana/blob/main/app/page.tsx): `app/page.tsx`
- [Landing page](https://github.com/razaele0003/pacana/blob/main/components/landing.tsx): `components/landing.tsx`
- [Workspace entry](https://github.com/razaele0003/pacana/blob/main/app/app/page.tsx): `app/app/page.tsx`
- [Windows app](https://github.com/razaele0003/pacana/blob/main/desktop/main.cjs): `desktop/main.cjs`

### Focus workspace

- [Pacana workspace](https://github.com/razaele0003/pacana/blob/main/components/pacana.tsx): `components/pacana.tsx`
- [Focus engine](https://github.com/razaele0003/pacana/blob/main/core/engine.ts): `core/engine.ts`
- [Clock scheduling](https://github.com/razaele0003/pacana/blob/main/core/schedule.ts): `core/schedule.ts`
- [App state model](https://github.com/razaele0003/pacana/blob/main/core/model.ts): `core/model.ts`
- [Fullscreen timer](https://github.com/razaele0003/pacana/blob/main/components/fullscreen-timer.tsx): `components/fullscreen-timer.tsx`
- [Journal photos](https://github.com/razaele0003/pacana/blob/main/components/log-photo.tsx): `components/log-photo.tsx`
- [Ringtone browser](https://github.com/razaele0003/pacana/blob/main/components/ringtone-browser.tsx): `components/ringtone-browser.tsx`

### Cappy companion

- [Interactive companion](https://github.com/razaele0003/pacana/blob/main/components/interactive-companion.tsx): `components/interactive-companion.tsx`
- [Autonomous behavior](https://github.com/razaele0003/pacana/blob/main/lib/capy-npc/autonomous-controller.ts): `lib/capy-npc/autonomous-controller.ts`
- [Movement geometry](https://github.com/razaele0003/pacana/blob/main/lib/capy-npc/obstacle-manager.ts): `lib/capy-npc/obstacle-manager.ts`
- [Capybara sprite](https://github.com/razaele0003/pacana/blob/main/components/capy-sprite.tsx): `components/capy-sprite.tsx`
- [Companion sounds](https://github.com/razaele0003/pacana/blob/main/lib/companion-sound.ts): `lib/companion-sound.ts`

### Local services

- [Local state store](https://github.com/razaele0003/pacana/blob/main/data/store.ts): `data/store.ts`
- [Backup validation](https://github.com/razaele0003/pacana/blob/main/data/backup.ts): `data/backup.ts`
- [Browser audio](https://github.com/razaele0003/pacana/blob/main/adapters/browser.ts): `adapters/browser.ts`
- [Ringtone definitions](https://github.com/razaele0003/pacana/blob/main/core/ringtones.ts): `core/ringtones.ts`

### Other components

- **User**

## Connections

- User → Web entry: opens (evidence: `README.md`)
- Web entry → Landing page: renders (evidence: `app/page.tsx`)
- User → Workspace entry: opens (evidence: `README.md`)
- Workspace entry → Pacana workspace: renders (evidence: `app/app/page.tsx`)
- Pacana workspace → Focus engine: reconciles state (evidence: `components/pacana.tsx`)
- Pacana workspace → Clock scheduling: gets day key (evidence: `components/pacana.tsx`)
- Pacana workspace → Local state store: transacts state (evidence: `components/pacana.tsx`)
- Pacana workspace → Browser audio: unlocks audio (evidence: `components/pacana.tsx`)
- Pacana workspace → Fullscreen timer: renders (evidence: `components/pacana.tsx`)
- Pacana workspace → Interactive companion: renders (evidence: `components/pacana.tsx`)
- Pacana workspace → Ringtone browser: renders (evidence: `components/pacana.tsx`)
- Pacana workspace → Journal photos: uses (evidence: `components/pacana.tsx`)
- Focus engine → Clock scheduling: gets next clock (evidence: `core/engine.ts`)
- Focus engine → App state model: uses state types (evidence: `core/engine.ts`)
- Local state store → App state model: stores state (evidence: `data/store.ts`)
- Local state store → Backup validation: uses validation (evidence: `data/store.ts`)
- Backup validation → App state model: validates state (evidence: `data/backup.ts`)
- Browser audio → App state model: uses settings (evidence: `adapters/browser.ts`)
- Browser audio → Ringtone definitions: plays definitions (evidence: `adapters/browser.ts`)
- Ringtone browser → App state model: uses ringtone types (evidence: `components/ringtone-browser.tsx`)
- Ringtone browser → Ringtone definitions: shows choices (evidence: `components/ringtone-browser.tsx`)
- Interactive companion → Autonomous behavior: controls behavior (evidence: `components/interactive-companion.tsx`)
- Interactive companion → Capybara sprite: renders (evidence: `components/interactive-companion.tsx`)
- Autonomous behavior → Capybara sprite: uses poses (evidence: `lib/capy-npc/autonomous-controller.ts`)
- Autonomous behavior → Companion sounds: plays cues (evidence: `lib/capy-npc/autonomous-controller.ts`)
- Autonomous behavior → Movement geometry: uses geometry (evidence: `lib/capy-npc/autonomous-controller.ts`)
