# ahmednajibe/wird architecture

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

- Interactive diagram: https://gitdiagram.com/ahmednajibe/wird
- Repository: https://github.com/ahmednajibe/wird

## Overview

Wird is a local-first daily learning tracker. A learner configures a weekly time budget and imports a plan, then the app schedules track sessions (including optional Quran memorization/review), records task completion, and updates points, streaks, and projections. The browser UI talks to a loopback API; the service coordinates planning and persistence in SQLite. The README documents calendar/fasting adjustments, bilingual RTL/LTR UI, backups, and plan export/import. Edges reflect shown calls or README claims; unsampled page and repository internals are represented by their existing directories.

Main entry points: [`src/server/service.ts`](https://github.com/ahmednajibe/wird/blob/master/src/server/service.ts) (Application service), [`src/web/App.tsx`](https://github.com/ahmednajibe/wird/blob/master/src/web/App.tsx) (App and pages), [`src/web/client/client.ts`](https://github.com/ahmednajibe/wird/blob/master/src/web/client/client.ts) (Typed API client), [`src/server/routes.ts`](https://github.com/ahmednajibe/wird/blob/master/src/server/routes.ts) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser experience"]
  node_webapp["App and pages<br/>[App.tsx]"]
  node_planui["Plan and import"]
  node_todayui["Daily learning<br/>[Today.tsx]"]
  node_quranui["Quran view<br/>[Quran.tsx]"]
  node_insightsui["Tracks and stats"]
  node_localization["Bilingual interface"]
  node_client["Typed API client<br/>[client.ts]"]
end

subgraph group_api["Local API"]
  node_serverapp["HTTP application<br/>[app.ts]"]
  node_routes["API routes<br/>[routes.ts]"]
  node_views["Dashboard views<br/>[views.ts]"]
  node_service["Application service<br/>[service.ts]"]
  node_importer["Plan import<br/>[importer.ts]"]
end

subgraph group_engine["Learning domain engine"]
  node_catalog["Track catalog<br/>[catalog.ts]"]
  node_planner["Session planning<br/>[planner.ts]"]
  node_progress["Progress ledger<br/>[progress.ts]"]
  node_quran["Quran scheduling<br/>[quran.ts]"]
  node_calendar["Calendar and fasting<br/>[calendar.ts]"]
  node_scoring["Points and streaks<br/>[streak.ts]"]
  node_projections["Finish projections<br/>[projections.ts]"]
  node_settings["Settings and timezone<br/>[settings.ts]"]
end

subgraph group_storage["Local persistence"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_repositories["Task and domain repositories"]
  node_backups["Local backups<br/>[backup.ts]"]
end

node_learner(("Learner"))
node_localhost(("Local browser"))

node_learner -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_planui
node_webapp -->|"routes to"| node_todayui
node_webapp -->|"routes to"| node_quranui
node_webapp -->|"routes to"| node_insightsui
node_webapp -->|"provides"| node_localization
node_planui -->|"requests"| node_client
node_todayui -.->|"requests"| node_client
node_quranui -.->|"requests"| node_client
node_insightsui -.->|"requests"| node_client
node_client -->|"fetches API"| node_localhost
node_localhost -->|"serves locally"| node_serverapp
node_serverapp -->|"registers"| node_routes
node_routes -->|"builds views"| node_views
node_routes -->|"dispatches"| node_service
node_routes -.->|"validates imports"| node_importer
node_service -->|"plans sessions"| node_planner
node_service -->|"synchronizes"| node_quran
node_service -->|"uses calendar"| node_calendar
node_service -->|"calculates progress"| node_scoring
node_service -->|"builds catalog"| node_catalog
node_service -.->|"reads settings"| node_settings
node_planner -->|"credits minutes"| node_progress
node_planner -->|"uses sessions"| node_quran
node_scoring -->|"derives baseline"| node_planner
node_scoring -->|"scores ledger"| node_progress
node_service -.->|"calculates estimates"| node_projections
node_service -->|"uses repositories"| node_repositories
node_repositories -.->|"reads and writes"| node_database
node_serverapp -->|"initializes"| node_database
node_database -.->|"backs up"| node_backups
node_importer -.->|"imports plan data"| node_catalog

click node_webapp "https://github.com/ahmednajibe/wird/blob/master/src/web/App.tsx"
click node_planui "https://github.com/ahmednajibe/wird/tree/master/src/web/pages"
click node_todayui "https://github.com/ahmednajibe/wird/blob/master/src/web/pages/Today.tsx"
click node_quranui "https://github.com/ahmednajibe/wird/blob/master/src/web/pages/Quran.tsx"
click node_insightsui "https://github.com/ahmednajibe/wird/tree/master/src/web/pages"
click node_localization "https://github.com/ahmednajibe/wird/tree/master/src/web/i18n"
click node_client "https://github.com/ahmednajibe/wird/blob/master/src/web/client/client.ts"
click node_serverapp "https://github.com/ahmednajibe/wird/blob/master/src/server/app.ts"
click node_routes "https://github.com/ahmednajibe/wird/blob/master/src/server/routes.ts"
click node_views "https://github.com/ahmednajibe/wird/blob/master/src/server/views.ts"
click node_service "https://github.com/ahmednajibe/wird/blob/master/src/server/service.ts"
click node_importer "https://github.com/ahmednajibe/wird/blob/master/src/server/importer.ts"
click node_catalog "https://github.com/ahmednajibe/wird/blob/master/src/shared/catalog.ts"
click node_planner "https://github.com/ahmednajibe/wird/blob/master/src/shared/planner.ts"
click node_progress "https://github.com/ahmednajibe/wird/blob/master/src/shared/progress.ts"
click node_quran "https://github.com/ahmednajibe/wird/blob/master/src/shared/quran.ts"
click node_calendar "https://github.com/ahmednajibe/wird/blob/master/src/shared/calendar.ts"
click node_scoring "https://github.com/ahmednajibe/wird/blob/master/src/shared/streak.ts"
click node_projections "https://github.com/ahmednajibe/wird/blob/master/src/shared/projections.ts"
click node_settings "https://github.com/ahmednajibe/wird/blob/master/src/shared/settings.ts"
click node_database "https://github.com/ahmednajibe/wird/blob/master/src/server/db.ts"
click node_repositories "https://github.com/ahmednajibe/wird/tree/master/src/server"
click node_backups "https://github.com/ahmednajibe/wird/blob/master/src/server/backup.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_webapp,node_planui,node_todayui,node_quranui,node_insightsui,node_localization,node_client,node_localhost toneBlue
class node_serverapp,node_routes,node_views,node_service,node_importer toneAmber
class node_catalog,node_planner,node_progress,node_quran,node_calendar,node_scoring,node_projections,node_settings toneMint
class node_database,node_repositories,node_backups toneRose
class node_learner toneIndigo
```

## Components

### Browser experience

- [App and pages](https://github.com/ahmednajibe/wird/blob/master/src/web/App.tsx): `src/web/App.tsx`
- [Plan and import](https://github.com/ahmednajibe/wird/tree/master/src/web/pages): `src/web/pages`
- [Daily learning](https://github.com/ahmednajibe/wird/blob/master/src/web/pages/Today.tsx): `src/web/pages/Today.tsx`
- [Quran view](https://github.com/ahmednajibe/wird/blob/master/src/web/pages/Quran.tsx): `src/web/pages/Quran.tsx`
- [Tracks and stats](https://github.com/ahmednajibe/wird/tree/master/src/web/pages): `src/web/pages`
- [Bilingual interface](https://github.com/ahmednajibe/wird/tree/master/src/web/i18n): `src/web/i18n`
- [Typed API client](https://github.com/ahmednajibe/wird/blob/master/src/web/client/client.ts): `src/web/client/client.ts`

### Local API

- [HTTP application](https://github.com/ahmednajibe/wird/blob/master/src/server/app.ts): `src/server/app.ts`
- [API routes](https://github.com/ahmednajibe/wird/blob/master/src/server/routes.ts): `src/server/routes.ts`
- [Dashboard views](https://github.com/ahmednajibe/wird/blob/master/src/server/views.ts): `src/server/views.ts`
- [Application service](https://github.com/ahmednajibe/wird/blob/master/src/server/service.ts): `src/server/service.ts`
- [Plan import](https://github.com/ahmednajibe/wird/blob/master/src/server/importer.ts): `src/server/importer.ts`

### Learning domain engine

- [Track catalog](https://github.com/ahmednajibe/wird/blob/master/src/shared/catalog.ts): `src/shared/catalog.ts`
- [Session planning](https://github.com/ahmednajibe/wird/blob/master/src/shared/planner.ts): `src/shared/planner.ts`
- [Progress ledger](https://github.com/ahmednajibe/wird/blob/master/src/shared/progress.ts): `src/shared/progress.ts`
- [Quran scheduling](https://github.com/ahmednajibe/wird/blob/master/src/shared/quran.ts): `src/shared/quran.ts`
- [Calendar and fasting](https://github.com/ahmednajibe/wird/blob/master/src/shared/calendar.ts): `src/shared/calendar.ts`
- [Points and streaks](https://github.com/ahmednajibe/wird/blob/master/src/shared/streak.ts): `src/shared/streak.ts`
- [Finish projections](https://github.com/ahmednajibe/wird/blob/master/src/shared/projections.ts): `src/shared/projections.ts`
- [Settings and timezone](https://github.com/ahmednajibe/wird/blob/master/src/shared/settings.ts): `src/shared/settings.ts`

### Local persistence

- [SQLite database](https://github.com/ahmednajibe/wird/blob/master/src/server/db.ts): `src/server/db.ts`
- [Task and domain repositories](https://github.com/ahmednajibe/wird/tree/master/src/server): `src/server`
- [Local backups](https://github.com/ahmednajibe/wird/blob/master/src/server/backup.ts): `src/server/backup.ts`

### Other components

- **Learner**
- **Local browser**

## Connections

- Learner → App and pages: uses (evidence: `README.md`)
- App and pages → Plan and import: routes to (evidence: `src/web/App.tsx`)
- App and pages → Daily learning: routes to (evidence: `src/web/App.tsx`)
- App and pages → Quran view: routes to (evidence: `src/web/App.tsx`)
- App and pages → Tracks and stats: routes to (evidence: `src/web/App.tsx`)
- App and pages → Bilingual interface: provides (evidence: `src/web/App.tsx`)
- Plan and import → Typed API client: requests (evidence: `src/web/pages/Plan.tsx`)
- Daily learning → Typed API client: requests
- Quran view → Typed API client: requests
- Tracks and stats → Typed API client: requests (evidence: `src/web/pages/Plan.tsx`)
- Typed API client → Local browser: fetches API (evidence: `src/web/client/client.ts`)
- Local browser → HTTP application: serves locally (evidence: `README.md`)
- HTTP application → API routes: registers (evidence: `src/server/app.ts`)
- API routes → Dashboard views: builds views (evidence: `src/server/routes.ts`)
- API routes → Application service: dispatches (evidence: `src/server/routes.ts`)
- API routes → Plan import: validates imports (evidence: `src/server/routes.ts`)
- Application service → Session planning: plans sessions (evidence: `src/server/service.ts`)
- Application service → Quran scheduling: synchronizes (evidence: `src/server/service.ts`)
- Application service → Calendar and fasting: uses calendar (evidence: `src/server/service.ts`)
- Application service → Points and streaks: calculates progress (evidence: `src/server/service.ts`)
- Application service → Track catalog: builds catalog (evidence: `src/server/service.ts`)
- Application service → Settings and timezone: reads settings (evidence: `src/server/service.ts`)
- Session planning → Progress ledger: credits minutes (evidence: `src/shared/planner.ts`)
- Session planning → Quran scheduling: uses sessions (evidence: `src/shared/planner.ts`)
- Points and streaks → Session planning: derives baseline (evidence: `src/shared/streak.ts`)
- Points and streaks → Progress ledger: scores ledger (evidence: `src/shared/streak.ts`)
- Application service → Finish projections: calculates estimates
- Application service → Task and domain repositories: uses repositories (evidence: `src/server/service.ts`)
- Task and domain repositories → SQLite database: reads and writes (evidence: `src/server/app.ts`)
- HTTP application → SQLite database: initializes (evidence: `src/server/app.ts`)
- SQLite database → Local backups: backs up (evidence: `src/server/db.ts`)
- Plan import → Track catalog: imports plan data