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. Eachsrc/index.tsis a barrel that re-exports a set of single-concept modules (e.g.habitsre-exportscrud,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.tsis ~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 catalog (12)#
The 12 tracked Nx projects in arete, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 12 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
domain (12)#
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.
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.
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).
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.
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.)
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.
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.
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.
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.
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.
analyzeProductiveHours27categorizeActivity27compareEstimateVsActual27detectPlanningFallacy27generateTimeInsights27getAuditQuadrantTimeDistribution27getTimeAuditReport27getTimeAuditStats27identifyTimeWasters27logTimeEntry27Vision, 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).
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.