# Arete — Systems Deep Dive

> The `libs/arete/` area: twelve Nx libraries that implement the
> **personal-development / life-mastery domain** — habits, goals, journaling,
> time, vision, balance, gamification, AI coaching, and affirmations — as pure,
> framework-grounded TypeScript, plus a generated V1 API client.

## What this area is

Arete is Oshun's "personal development & life mastery" customer domain, themed
around Stephen Covey's _7 Habits of Highly Effective People_ and a wider canon
of behaviour-change frameworks (James Clear's _Atomic Habits_, BJ Fogg's _Tiny
Habits_, Brian Moran's _12 Week Year_, Gabriele Oettingen's WOOP, Martin
Seligman's PERMA, Cal Newport's _Deep Work_, GTD, Ikigai, Simon Sinek's Golden
Circle). Every project carries the `scope:arete`, `layer:domain`, `type:lib` Nx
tags, and each is a `@nx/js:tsc` buildable library with its own Vitest suite.

The defining architectural property of the domain libraries is that they are
**pure, in-memory domain logic**: they import their record types from
`@arete/core` and operate on plain objects passed in by the caller, with no
database access, no network, and no external AI APIs inside the library. The
"AI" in `@arete/ai-coach` and `@arete/affirmations` is explicitly rule-based NLP
and template generation ("No external APIs required" / "No external AI APIs
required" in their module headers), so the logic is deterministic and testable.
Persistence lives elsewhere — in `@arete/core`'s Drizzle schema and the
consuming service's repositories — which keeps the framework algorithms free of
I/O.

`@arete/core` sits at the bottom of the area's dependency graph. It owns the Zod
validation schemas (`schemas.ts`, "All 58 schemas with full validation rules")
and the Drizzle ORM table definitions (`db-schema.ts`, ~3,260 lines) plus seed
data (`db-seed.ts`). Across the rest of the area the recurring import is
`import type { ... } from '@arete/core'` (the most-imported `@arete/*` package
in the repo), so `core` is the shared type spine and every other domain library
is a fan of leaf modules hanging off it.

The thirteenth directory under `libs/arete/` — `database/` — is a Prisma package
(`schema.prisma`, a migration, and a generated client). It carries **no
`project.json`**, so it is not one of the twelve tracked Nx projects and is not
documented as an entity below; it is supporting database infrastructure,
distinct from `@arete/core`'s Drizzle schema.

## How the area is shaped

Two of the twelve projects are infrastructural and ten are framework engines:

- **`@arete/core`** — the shared Zod + Drizzle type/schema foundation everything
  else builds on.
- **`arete-api-client`** (package `@arete/api-client`) — a generated, typed HTTP
  client over the `/api/v1/arete/*` REST surface; the only project whose Nx name
  is not `@arete/...`.
- The remaining ten (`affirmations`, `ai-coach`, `balance`, `gamification`,
  `goals`, `habits`, `journal`, `seven-habits`, `time`, `vision`) are domain
  engines. Each `src/index.ts` is a barrel that re-exports a set of
  single-concept modules (e.g. `habits` re-exports `crud`, `habit-loop`,
  `four-laws`, `streaks`, `recovery`, … — thirteen modules), and each module
  file pairs with a `.spec.ts`. Module files run from a few hundred to well over
  a thousand lines (`ai-coach/src/nlp-analytics.ts` is ~1,330), and the code is
  framework-specific rather than generic CRUD.

There are no README files in the area; each library's module headers and the
`@arete/*` JSDoc `@packageDocumentation` block are the in-tree documentation,
and the narrative architecture lives under `DOMAINS/arete/` and
`V1/features/domain-arete.md`.

## How it fits the wider system

The domain libraries are consumed by the Arete service, `apps/arete/api`, which
imports `@arete/core` (heavily) and `@arete/ai-coach` and wraps the pure logic
with repositories and HTTP handlers (see its `__tests__/` covering balance,
coach, gamification, goals, habits, journal, time, users). `@arete/core`'s
Drizzle tables back those repositories. `arete-api-client` is the other side of
that boundary: it is generated from the V1 OpenAPI spec by
`libs/openapi/scripts/generate-oshun-v1-api-clients.ts` and gives typed callers
`list`/`create`/`get`/`upsert`/`tombstone` against each Arete V1 resource.

The boundary out to other Oshun domains is deliberately narrow and typed:
`@arete/ai-coach`'s `cross-domain.ts` emits optional, "invitational"
recommendation links to a fixed set of adjacent domains
(`'tara' | 'nisaba' | 'veritas' | 'assistant' | 'iris'`) from Arete review
signals, rather than calling those domains directly. Walk the "used by" edges on
any node below to see exactly who depends on it.

## Entity reference

### @arete/core

The foundation of the area (`libs/arete/core/src`). `schemas.ts` is a single Zod
module declaring the full Arete domain model (its header states "All 58 schemas
with full validation rules and inferred TypeScript types") with reusable field
helpers (`id`, `userId`, ISO `datetime`, `dateOnly`, `timeOfDay` regexes) and
Covey-specific enums such as `MaturityStageSchema`
(`dependence | independence | interdependence`). `db-schema.ts` (~3,260 lines)
is the Drizzle ORM PostgreSQL schema — legacy tables plus the V1 contract
records (habits, goals, journals, vision, time, balance, gamification,
accountability) — and `db-seed.ts` provides seed data. It is the most-imported
`@arete/*` package; the other domain libraries take their record types from
here.

### @arete/habits

The habit-engine library (`libs/arete/habits/src`), the largest domain engine by
module count. Its barrel re-exports thirteen modules grounded in named
behaviour-change theory: `habit-loop` (Atomic Habits cue-routine-reward),
`four-laws` (James Clear's Four Laws, with the inverse laws for breaking habits
— `makeItObvious`, implementation-intention generation, etc.), `stacking` (Tiny
Habits), `streaks` (a forgiveness/grace-window/vacation-mode streak system with
`evaluateStreakGraceWindow`), `recovery`, `identity`, `keystone`, `celebration`,
`reminders`, `friction`, `interventions`, `analytics`, and `crud`. Operates on
`Habit`/`HabitCompletion` types from `@arete/core`; the
`__tests__/v1-streak-recovery-contract.spec.ts` pins the V1 grace-window and
recovery-ladder behaviour.

### @arete/goals

Pure goal-management logic (`libs/arete/goals/src`). Eight modules: `crud`,
`hierarchy`, `smart` (SMART goals), `okr` (Objectives & Key Results), `woop`
(Oettingen's Wish-Outcome-Obstacle-Plan mental-contrasting workflow with
implementation intentions), `twelve-week-year` (Brian Moran's 12 Week Year —
weekly plans, lead/lag indicators, Weekly Accountability Meetings, buffer-week
review), `progress`, and `analytics`. The header describes it as "Pure domain
logic"; modules define their own framework types (e.g. `WeeklyPlan`,
`LeadIndicator`/`LagIndicator`) and consume goal types from `@arete/core`.

### @arete/journal

The journaling and reflection engine (`libs/arete/journal/src`), nine modules:
`crud` (rich text, tagging, version history), `morning-pages` (Julia Cameron's
750-word practice), `five-minute-journal`, `gratitude`, `thought-records` (CBT
thought records with cognitive-distortion identification, evidence-for/against,
balanced thoughts), `worry-journal` (scheduled worry time), `prompted-journal`
(300+ prompts), `reflection` (daily→annual workflows), and `analytics`
(sentiment / emotion / insights). Functions are pure and operate on in-memory
data (`thought-records.ts` notes "All functions are pure and operate on
in-memory data"), using `randomUUID` from `crypto` and `ThoughtRecord` types
from `@arete/core`.

### @arete/time

Time-management and productivity logic (`libs/arete/time/src`). Modules cover
the `eisenhower` matrix (urgency/importance scoring into Covey's quadrants, with
delegation/elimination suggestions and Q2 protection), `gtd-inbox` and
`gtd-review` (Getting Things Done capture and the 3-phase weekly review),
`big-rocks`, `time-blocking`, `pomodoro`, `deep-work` (Cal Newport), and
`daily-planning` (MIT, 1:4:5, shutdown rituals). The barrel also re-exports a
curated slice of `time-audit` (e.g. `detectPlanningFallacy`,
`analyzeProductiveHours`, `identifyTimeWasters`) with an aliased
`getAuditQuadrantTimeDistribution` to avoid a name clash with the Eisenhower
module.

### @arete/seven-habits

The Stephen Covey _7 Habits_ engine (`libs/arete/seven-habits/src`), one module
per habit plus a relationship-trust module: `be-proactive` (Circle of Influence
vs Circle of Concern, control classification, proactive-language alternatives),
`begin-with-end`, `put-first-things-first`, `think-win-win`,
`seek-to-understand`, `synergize`, `sharpen-the-saw`, and
`emotional-bank-account`. It consumes Covey-specific types from `@arete/core`
such as `CircleOfInfluence` and `MaturityStage`. This is the thematic heart of
the whole domain — the framework the rest of Arete is organised around.

### @arete/vision

Vision, purpose, and legacy tooling (`libs/arete/vision/src`), six modules:
`vision-board`, `mission-statement`, `values-clarification`, `ikigai` (the
four-circle Japanese framework, with `findIntersections` computing
passion/mission/profession/vocation overlaps via `IkigaiIntersections`),
`golden-circle` (Simon Sinek's Why-How-What), and `legacy`. Modules are
self-contained (Ikigai defines its own `IkigaiExploration`/`IkigaiSection` types
and uses `randomUUID` from `crypto`).

### @arete/balance

Life-balance and wellness assessment (`libs/arete/balance/src`), seven modules:
`wheel-of-life`, `wellness-dimensions` (the eight dimensions of wellness),
`perma` (Seligman's Positive Emotion / Engagement / Relationships / Meaning /
Accomplishment, scored per element with low/moderate/high insight banding),
`mood-tracking`, `sleep-tracking`, `energy-management`, and `life-satisfaction`
(the SWLS — Satisfaction With Life Scale). Each module defines its own
assessment/entry/insight types (e.g. `PERMAEntry`, `PERMAInsight`).

### @arete/gamification

The gamification engine (`libs/arete/gamification/src`), eight modules: `points`
(XP/coins/gems, multipliers, consistency bonuses), `badges` (50+ badges),
`levels` (a 20-level exponential XP curve defined inline as `LEVEL_DEFINITIONS`,
with per-level titles, `xpRequired`/`xpTotal`, and unlockable perks),
`leaderboards`, `accountability` (partners and check-ins), `contracts`
(commitment contracts with stakes, referees, anti-charities and outcome
processing — _not_ wire contracts), `challenges`, and `rewards`. Consumes
`Level`/`Points`/`CommitmentContract` types from `@arete/core`. (`contracts.ts`
uses a `Math.random()`-based UUID v4 string generator, annotated as legitimate;
most other modules use `crypto.randomUUID`.)

### @arete/ai-coach

The coaching and analytics layer (`libs/arete/ai-coach/src`), nine modules of
**rule-based** intelligence with "No external APIs required": `coaching`
(conversational CBT/goals/habits/reflection/motivation), `recommendations`,
`patterns` (habit/mood/energy/productivity pattern recognition), `nlp-analytics`
(~1,330 lines of rule-based sentiment/emotion/topic/trend/summarisation NLP over
journal entries), `notifications` (smart-timing nudges), `weekly-review`, the
`coaching-summary-card` and `continuity-card` view-model builders, and
`cross-domain` (typed, optional recommendation links to
`tara`/`nisaba`/`veritas`/ `assistant`/`iris`). It is one of the two `@arete/*`
packages imported outside the area (by `apps/arete/api`), and ships a
`__tests__/v1-weekly-review-contract.spec.ts`.

### @arete/affirmations

The affirmation engine (`libs/arete/affirmations/src`), two modules:
`management` (a 500+ curated affirmation library with CRUD, scheduling, widgets,
reminders and stats, exposing `AFFIRMATION_LIBRARY` / `ALL_CATEGORIES` /
`getAffirmationsByCategory` / `searchAffirmations`) and `ai-affirmations`
(rule-based generation via templates, keyword substitution and personalisation,
explicitly "No external AI APIs required", taking `GoalInput`/`ValueInput` and
composing from the curated library). Self-contained — `ai-affirmations` imports
only from its sibling `management` module, not from `@arete/core`.

### arete-api-client

The generated, typed V1 HTTP client (`libs/arete/api-client/src`; Nx project
name `arete-api-client`, npm package `@arete/api-client` — the only entity whose
Nx name is not `@arete/...`). `generated/openapi.ts` (~2,460 lines) is the
`openapi-typescript` output for the `/api/v1/arete/*` surface, and `client.ts`
(generated by `libs/openapi/scripts/generate-oshun-v1-api-clients.ts`) builds
`createAreteApiClient(options)` returning an `AreteApiClient` with a uniform
`ResourceClient` (`list` / `create` / `get` / `upsert` / `tombstone`) for each
V1 resource: habits, goals, routines, check-ins, journal-entries,
weekly-reviews, streak-records, friction-signals, interventions, and
coaching-summaries. It is transport-agnostic (an injectable `FetchLike`) and
raises `OshunApiClientError` on non-OK responses. Unlike the domain engines it
does not depend on `@arete/core`; it is purely the wire-level access layer.