Eve library

Arete Architecture

Guide

Revision 1

On this page

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#

text
       ┌──────────────────────────────┐
       │        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: