# Arete Architecture

> **Canonical source:** the canonical architecture document for this domain is
> [`deep-dive/architecture.md`](./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`](../../../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/`](adr/) for the formal records:

- [0001 — Repository pattern with Memory + Pg implementations](adr/0001-repository-pattern.md)
- [0002 — Server-Sent Events for coach chat streaming](adr/0002-coach-sse.md)
- [0003 — Drizzle as schema source of truth](adr/0003-drizzle-source-of-truth.md)
