Canonical source: the canonical architecture document for this domain is
deep-dive/architecture.md, rendered in the docs center. This file is its operational companion (service topology, APIs, schemas, runtime detail) — reconciled by linking, not duplicated (§2, §13).
The Arete domain implements Stephen Covey's 7 Habits of Highly Effective People, James Clear's Atomic Habits, and the Tiny Habits / OKR / 12 Week Year frameworks as a working personal-development platform. The codebase splits cleanly into 11 domain libraries, three apps, and a single PostgreSQL schema.
Component topology#
┌──────────────────────────────┐
│ apps/arete/api │ Fastify + Drizzle
│ (95 endpoints, JWT, SSE) │
└──────────────┬───────────────┘
│ shares schema with
▼
┌──────────────────────────────┐
│ libs/arete/core │ Drizzle tables + Zod schemas
│ (48 tables, 18 enums) │
└──────────────────────────────┘
▲
│ imports algorithms from
│
┌──────────────────────────────────────────┐
│ libs/arete/{habits, goals, journal, │
│ vision, time, balance, seven-habits, │
│ affirmations, ai-coach, gamification} │
└──────────────────────────────────────────┘
▲ ▲
│ consumes │ consumes
│ │
apps/arete/web (React + Vite) apps/arete/mobile (React Native)
Library responsibilities#
| Library | Responsibility |
|---|---|
@arete/core |
Drizzle tables, Zod request/response schemas, default seed data |
@arete/habits |
4 Laws of Behavior Change, habit loop, streak math, identity-based habits |
@arete/goals |
SMART / SMARTER scoring, OKRs, WOOP, 12 Week Year, hierarchy cascade |
@arete/journal |
Prompted journal, CBT thought records, sentiment lexicon, morning pages |
@arete/vision |
Mission statement builder, values clarification, ikigai, vision boards |
@arete/time |
Eisenhower scoring, GTD inbox/review, pomodoro, time-blocking, daily/weekly planning |
@arete/balance |
Wheel of Life, SAMHSA Eight Dimensions, PERMA-Profiler, mood/sleep/energy tracking |
@arete/seven-habits |
Be Proactive, Begin with End in Mind, Put First Things First, Think Win-Win, Seek First to Understand, Synergize, Sharpen the Saw |
@arete/affirmations |
500+ curated affirmations + AI-template engine |
@arete/ai-coach |
CBT prompting, goal/habit/reflection coaching, sentiment + pattern detection |
@arete/gamification |
Badge catalog (54), level curve, accountability partner effectiveness scoring, leaderboards, challenges |
Each library publishes a documented public API and is independently testable. Coverage is at or above 80% on every library (statements):
| Library | Statements | Functions |
|---|---|---|
| affirmations | 97.59% | 96.66% |
| ai-coach | 94.88% | 98.59% |
| balance | 96.61% | 98.05% |
| core | 91.77% | 6.25% (mostly type-only) |
| gamification | 94.85% | 68.98% |
| goals | 94.92% | 98.88% |
| habits | 93.80% | 99.21% |
| journal | 98.24% | 98.92% |
| seven-habits | 97.96% | 98.90% |
| time | 96.10% | 99.23% |
| vision | 98.43% | 98.82% |
Repository pattern#
Every API route delegates persistence to a *Repository interface. Production
wires the Drizzle-backed Pg…Repository; tests inject the in-memory equivalent.
The split is in
apps/arete/api/src/repositories.
| Domain | Memory | Pg |
|---|---|---|
| Users | MemoryUserRepository |
PgUserRepository |
| Habits | MemoryHabitRepository |
PgHabitRepository |
| Goals | MemoryGoalRepository |
PgGoalRepository |
| Journal | MemoryJournalRepository |
PgJournalRepository |
| Balance | MemoryBalanceRepository |
PgBalanceRepository |
| Vision | MemoryVisionRepository |
PgVisionRepository |
| Time | MemoryTimeRepository |
PgTimeRepository |
| Gamification | MemoryGamificationRepository |
PgGamificationRepository |
| Coach | MemoryCoachRepository |
PgCoachRepository |
The same *Repository interface is asserted by both, so route handlers never
branch on backend.
Front ends#
apps/arete/web is a Vite-built React SPA with React Query for server state.
Pages live under src/pages/ and consume hooks under src/api/hooks/. The
Coach page subscribes to the live SSE stream.
apps/arete/mobile is a React Native (0.73) project. Hooks under src/hooks/
mirror the web hook surface. The chat screen consumes the same SSE stream via
streamChatMessage.
Auth & authorization#
@fastify/jwt issues HS256 tokens. Every authenticated route reads
request.user (decorated by plugins/auth.ts) and gates by ownership — e.g.
listing tasks always filters by userId === authUser.id. Cross-user access is
rejected with 404, never with a leak-by-403.
Architecture decisions#
See adr/ for the formal records: