Arete — Technical Specifications

Personal development and life mastery domain. Named after the Ancient Greek concept of excellence, virtue, and living up to one's full potential.

This document specifies what is implemented in the Arete domain. Every schema, field, enum value, table, endpoint, and configuration key below is traceable to source code under libs/arete/*, apps/arete/*, or libs/contracts/src/arete/.

The document is organized in layers matching the implementation: domain overview and library inventory first, then the Zod validation schemas, then the database schema (both legacy and V1 contract tables), then the API surface, events, configuration, and integration points. A new engineer should read §1–2 for orientation, then jump to whichever section matches the area they are working on.

1. Domain Overview#

The table below summarizes the domain's key properties at a glance. The arete_ table prefix is consistent across all 61 database tables and all enum types.

libs/arete/database/ contains only prisma/schema.prisma and a generated prisma/generated/schema.sql. It has no package.json or project.json, so it is not an Nx library and is not counted above. The authoritative schema for the domain is the Drizzle ORM schema in @arete/core (src/db-schema.ts).

2. Library Inventory#

Twelve libraries carry a package.json and project.json. All are tagged ["scope:arete", "layer:domain", "type:lib"]. The source modules column lists every module file under src/ for each library.

@arete/core carries runtime dependencies (@oshun/contracts, drizzle-orm, zod). The eight personal-development feature libraries, @arete/gamification, and @arete/ai-coach declare @arete/core as a peerDependency and carry no other runtime dependencies. @arete/api-client is a standalone generated client with no runtime dependency on @arete/core.

2.1 Applications#

@arete/api has the Nx tag set ["scope:arete", "type:app", "layer:service"].

3. Data Models — @arete/core/schemas.ts (56 Zod schemas)#

schemas.ts exports 56 *Schema constants. Each schema exports an inferred TypeScript type via z.infer. The numbered design comments in the file run 1–55 because two schemas (MaturityStageSchema enum and GratitudeItemSchema nested object) are sub-schemas of larger entities.

Shared field helpers (id, userId, datetime, dateOnly, timeOfDay) are defined once and reused. id/userId are z.string().uuid(); datetime is z.string().datetime() (ISO 8601); dateOnly matches YYYY-MM-DD; timeOfDay matches HH:mm (00:00–23:59).

The sub-sections below enumerate every schema in the file, grouped by the domain entity they represent.

3.1 Identity and Profile#

These schemas model the user and their defining personal context: who they are, what they value, what roles they inhabit, and where they stand on Covey's maturity continuum.

UserProfileSchema — user profile and preferences.

PersonalMissionSchema — mission statement with associated values.

ValueSchema — id, userId, name (1–100), description (≤2000), priority (int 1–10, 1 = highest), category (1–100).

RoleSchema — id, userId, name (1–100), description (≤2000), goals (array of uuid, default []), isActive (boolean, default true).

MaturityStageSchema — enum: dependence, independence, interdependence (Covey's maturity continuum).

3.2 Goals#

These schemas cover the full goal model: the base goal entity shared across all five frameworks, plus the framework-specific extensions and sub-entities.

GoalSchema — base goal with hierarchical nesting.

GoalTypeSchema — enum: annual, quarterly, monthly, weekly, daily.

GoalStatusSchema — enum: not_started, in_progress, completed, abandoned, paused.

SMARTGoalSchema — GoalSchema extended with specific, measurable, achievable, relevant, timeBound (each string, 1–2000). These are stored as additional columns on arete_goals rather than a separate table; see §5.1.

KeyResultSchema — id, okrId (uuid), description (1–1000), currentValue (number), targetValue (number), unit (1–50), score (number 0.0–1.0).

OKRSchema — id, userId, objective (1–1000), keyResults (KeyResultSchema[], 1–5), quarter (int 1–4), year (int 2000–2100), status (GoalStatusSchema, default not_started).

WOOPGoalSchema — id, userId, wish (1–1000), outcome (1–2000), obstacle (1–2000, the main internal obstacle), plan (1–2000, the if-then plan), status (GoalStatusSchema). Like SMART criteria, WOOP fields are columns on arete_goals rather than a separate table.

ImplementationIntentionSchema — id, userId, goalId (uuid), situation (1–1000, the "if" trigger), behavior (1–1000, the "then" action), strength (number 0–10).

3.3 Habits#

The habit schemas model the full cue-routine-reward lifecycle, completion records, streaks, and streak freezes. Note that the cue, routine, and reward sub-structures are validated individually before being stored as JSONB in the arete_habits table.

HabitSchema — a habit with cue-routine-reward loop and tracking stats.

HabitFrequencySchema — enum: daily, weekly, specific_days, flexible, x_per_week.

HabitCueSchema — type (enum: time, location, preceding_action, emotional_state), value (1–500), description (≤1000, default '').

HabitRoutineSchema — steps (array of 1–500-char strings, ≥1), starterStep (1–500, the tiny first step), durationMinutes (int 1–480), difficulty (int 1–5).

HabitRewardSchema — type (enum: intrinsic, extrinsic), description (1–1000), points (int ≥0, default 0).

HabitStackSchema — id, userId, name (1–200), habits (array of uuid, ≥1, ordered), triggerCue (HabitCueSchema).

HabitCompletionSchema — id, habitId (uuid), userId, date (YYYY-MM-DD), completedAt (datetime | null), notes (≤2000, default ''), quality (int 1–5 | null), skipped (boolean, default false), skipReason (≤500 | null).

StreakSchema — id, habitId (uuid), userId, current (int ≥0), best (int ≥0), startDate (YYYY-MM-DD), lastCompletionDate (YYYY-MM-DD | null), forgivenessDaysUsed (int ≥0, default 0), forgivenessDaysAllowed (int ≥0, default 1).

StreakFreezeSchema — id, streakId (uuid), userId, date (YYYY-MM-DD), reason (≤500, default ''), wasAutomatic (boolean, default false).

3.4 Journal#

The journal schemas cover the core entry record, prompts, templates, CBT thought records, and gratitude entries. The JournalEntrySchema is the primary record; the specialized schemas below are separate entities linked to it.

JournalEntrySchema — a journal entry with mood tracking and tagging.

JournalPromptSchema — id, text (5–1000), category (enum: gratitude, reflection, growth, creativity, mindfulness), isSystem (boolean, default false).

JournalTemplateSchema — id, name (1–200), type (enum: five_minute, morning_pages, evening_reflection, weekly_review, monthly_review), prompts (array of 1–1000-char strings, ≥1), structure (record<string, unknown>, default {}).

ThoughtRecordSchema — a CBT thought record. The emotionIntensity and newEmotionIntensity fields bracket the before/after mood shift produced by completing the thought record exercise.

GratitudeItemSchema — text (1–500), category (1–100).

GratitudeEntrySchema — id, userId, items (GratitudeItemSchema[], 1–10), date (YYYY-MM-DD).

3.5 Vision#

The vision schemas model digital vision boards and the items placed on them. The VisionBoardCategorySchema enum restricts board categories to the ten life areas used throughout the domain; the item type field determines whether the board cell contains an image, text, or a linked goal.

VisionBoardCategorySchema — enum: career, health, relationships, finances, personal_growth, spirituality, adventure, creativity, family, education.

VisionBoardItemSchema — id, boardId (uuid), type (enum: image, text, goal_link), content (1–5000), position ({ x, y }, both ≥0), size ({ w, h }, both ≥1), goalId (uuid | null).

VisionBoardSchema — id, userId, name (1–200), description (≤2000), isActive (boolean, default true), items (VisionBoardItemSchema[], default []), createdAt.

3.6 Time Management#

The time management schemas span both higher-level planning (weekly plans with big rocks, daily plans with MIT trios) and execution-level records (Pomodoro sessions, deep work sessions, and individual tasks in the Eisenhower matrix).

TaskQuadrantSchema — enum: Q1_urgent_important, Q2_not_urgent_important, Q3_urgent_not_important, Q4_not_urgent_not_important (Eisenhower matrix).

TaskSchema — id, userId, title (1–500), description (≤5000), quadrant (TaskQuadrantSchema), priority (int 1–10, 1 = highest), dueDate (YYYY-MM-DD | null), estimatedMinutes (int 1–1440 | null), completedAt (datetime | null), isRecurring (boolean, default false), tags (array of strings 1–50, default []).

BigRockSchema — id, userId, weekStart (YYYY-MM-DD, Monday), title (1–500), description (≤2000), roleId (uuid | null), isCompleted (boolean, default false), priority (int 1–7).

TimeBlockSchema — id, userId, date (YYYY-MM-DD), startTime (HH:mm), endTime (HH:mm), title (1–500), category (enum: deep_work, admin, meeting, personal, health, learning), isFlexible (boolean, default false).

WeeklyPlanSchema — id, userId, weekStart (YYYY-MM-DD), bigRocks (BigRockSchema[], default []), roles (array of uuid), review (≤5000), sharpenTheSaw (≤2000, planned renewal activities).

DailyPlanSchema — id, userId, date (YYYY-MM-DD), bigThree (array of exactly 3 strings 1–500), timeBlocks (TimeBlockSchema[], default []), morningRoutine (≤2000), eveningReview (≤2000).

PomodoroSessionSchema — id, userId, taskId (uuid | null), startedAt (datetime), duration (int 1–120, default 25), breakDuration (int 0–60, default 5), completed (boolean, default false), distractions (int ≥0, default 0).

DeepWorkSessionSchema — id, userId, startedAt (datetime), endedAt (datetime | null), focusScore (int 0–100 | null), objective (1–1000), accomplishments (≤5000), distractions (int ≥0).

3.7 Seven Habits#

These schemas directly model Covey's constructs: the Circle of Influence/Concern classification, and the Emotional Bank Account with per-relationship transaction histories.

CircleOfInfluenceSchema — id, userId, item (1–1000), circle (enum: concern, influence), actionable (boolean, default false), notes (≤2000).

EmotionalTransactionSchema — id, accountId (uuid), type (enum: deposit, withdrawal), description (1–1000), amount (int 1–10, magnitude), category (enum: courtesy, kindness, honesty, commitment, apology, forgiveness), date (datetime).

EmotionalBankAccountSchema — id, userId, relationshipName (1–200), balance (int, may be negative), lastTransaction (datetime | null), transactions (EmotionalTransactionSchema[], default []).

3.8 Balance and Wellness#

The wellness schemas cover life balance assessment (Wheel of Life), renewal activity planning, and daily biometric check-ins (mood, sleep, energy). The WellnessDimensionSchema enum is the shared vocabulary for dimension types across all three assessment tools.

WellnessDimensionSchema — enum: physical, mental, emotional, spiritual, social, financial, career, family, fun_recreation, personal_growth, custom.

WheelOfLifeDimensionSchema — dimensionType (WellnessDimensionSchema), customName (1–80, optional), customDescription (≤500, optional), rating (int 1–10), targetRating (int 1–10), notes (≤2000), actions (array of strings 1–500, default []). A .refine() enforces that customName is present whenever dimensionType is custom.

WheelOfLifeSchema — id, userId, dimensions (WheelOfLifeDimensionSchema[], ≥1), overallScore (number 0–10, computed), assessmentDate (YYYY-MM-DD), notes (≤5000).

RenewalActivitySchema — id, userId, dimension (WellnessDimensionSchema), activity (1–500), frequencyPerWeek (int 1–14), durationMinutes (int 1–480), notes (≤2000).

RenewalLogSchema — id, activityId (uuid), userId, date (YYYY-MM-DD), durationMinutes (int 1–480), quality (int 1–5), notes (≤2000).

MoodEntrySchema — id, userId, mood (int 1–5), energy (int 1–5), tags (array of strings 1–50, default []), notes (≤2000), date (datetime).

3.9 Affirmations#

AffirmationSchema — id, userId, text (1–1000), category (1–100), isActive (boolean, default true), frequency (enum: daily, weekly, on_demand, default daily), lastReviewedAt (datetime | null).

3.10 Gamification#

The gamification schemas model the three reward currencies (XP, coins, gems), the badge and leveling system, accountability partnerships, commitment contracts, and community challenges.

BadgeSchema — id, name (1–200), description (≤1000), category (1–100), icon (1–200), unlockCondition (1–1000, human-readable), points (int ≥0), tier (enum: bronze, silver, gold, platinum).

AchievementSchema — id, userId, badgeId (uuid), earnedAt (datetime | null), progress (number 0–100, default 0).

LevelSchema — level (int 1–100), title (1–200), xpRequired (int ≥0), xpTotal (int ≥0, cumulative), perks (array of strings 1–500, default []).

PointsSchema — id, userId, amount (int ≥1), type (enum: xp, coins, gems), source (1–500), earnedAt (datetime).

AccountabilityPartnerSchema — id, userId, partnerUserId (uuid), status (enum: pending, active, ended, default pending), sharedGoals (array of uuid, default []), createdAt.

CommitmentContractSchema — id, userId, goalId (uuid), stake ({ description (1–1000), amount (≥0) }), referee (uuid | null), deadline (YYYY-MM-DD), status (enum: active, completed, failed, default active).

ChallengeSchema — id, title (1–500), description (1–5000), category (1–100), startDate (YYYY-MM-DD), endDate (YYYY-MM-DD), participantCount (int ≥0, default 0), rules (array of strings 1–1000, ≥1), prizes (array of strings 1–500, default []).

4. V1 Contract Schemas — @oshun/contracts/arete#

libs/contracts/src/arete/index.ts defines a second, newer schema family — the "V1" contracts. These describe the humane-streak / friction-aware coaching model: a more psychologically sensitive alternative to binary pass/fail habit tracking. The arete_v1_* Drizzle tables (see §5.3) and @arete/api-client types are typed against these contracts.

The V1 model introduces concepts not present in the legacy schemas: a declared difficulty rating for each habit, a humane streak policy that distinguishes between skip, decline, partial, and miss, friction signals from multiple Oshun domains, and an intervention dispatch system that suggests corrective actions when friction is detected.

4.1 Contract enums#

The V1 contracts define 21 enums. The table below lists each schema and its values. Note that some of these (e.g., FrictionSignalSourceSchema) name other Oshun domains as valid signal sources — this is the primary cross-domain coupling point in the Arete codebase.

4.2 Contract entities#

The contract module exports thirteen entity schemas, each consumed by an arete_v1_* table: HabitSchema, RoutineSchema, GoalSchema, CheckInSchema, MissedDaySchema, JournalEntrySchema, WeeklyReviewSchema, PlanSchema, StreakRecordSchema, RecoveryRecordSchema, FrictionSignalSchema, InterventionSchema, CoachingSummarySchema. Supporting nested schemas include DeclaredCadenceSchema, HumaneStreakPolicySchema, RoutineStepSchema, GoalCompletionSchema, WeeklyReviewSectionSchema, PlanCommitmentSchema, StreakEventSchema, MoodSnapshotSchema, AreteMetricSchema, and AreteReferenceSchema.

Notable validation: DeclaredCadenceSchema uses .superRefine() to require daysOfWeek for a weekly cadence, targetCount + period for count-per-period, and triggerRef for on-trigger. HumaneStreakPolicySchema carries skipPreservesStreak, declinePreservesStreak, missGraceCadences (0–30), recoveryPromptAfterMisses (1–30), and visualLanguage (no-shame or neutral). The contract module also exports CHECK_IN_STREAK_TREATMENT, a Record<CheckInStatus, StreakTreatment> mapping each check-in status to its streak treatment.

5. Database Schema — @arete/core/db-schema.ts#

db-schema.ts exports Drizzle ORM table definitions, relations, enums, and raw SQL strings. ALL_ARETE_TABLES enumerates 61 tables; ALL_ARETE_ENUMS enumerates 39 pgEnum definitions (coachMessageRoleEnum is a 40th enum, defined inline and used by arete_coach_messages but not added to that array). All tables use the arete_ name prefix.

5.1 Legacy table groups#

The 48 legacy tables are organized into eleven functional groups. A few structural decisions are worth noting before reading the full list:

• SMART and WOOP are columns, not tables. arete_goals carries smart_specific, smart_measurable, smart_achievable, smart_relevant, smart_time_bound, and woop_wish, woop_outcome, woop_obstacle, woop_plan directly. There are no separate arete_smart_goals or arete_woop_goals tables.
• Goal hierarchy is modelled twice: a self-referential parent_goal_id on arete_goals, plus an explicit arete_goal_hierarchy join table with a unique (parent_goal_id, child_goal_id) index.
• Credentials are separated from arete_users: arete_user_credentials holds the bcrypt password_hash so the profile table can be SELECT *'d safely. arete_password_reset_tokens holds single-use, time-bounded reset tokens.
• Habit cue / routine / reward are stored as JSONB columns on arete_habits, not separate tables.
• Mood, sleep, energy are separate tables (arete_mood_entries, arete_sleep_entries, arete_energy_entries), each with a sequence column so multiple same-day entries are ordered.
• arete_habit_completions carries both the legacy fields and V1 check-in fields: status (arete_v1_check_in_status), engagement_percent, status_reason, streak_treatment (arete_v1_streak_treatment).
• arete_partner_invitations records outgoing partnership invites by email (a partner need not have an existing account).

5.2 Legacy enums (subset)#

The following PostgreSQL enum types are defined in ALL_ARETE_ENUMS, all prefixed arete_ in the database:

maturity_stage, goal_type, goal_status, habit_frequency, journal_prompt_category, vision_board_item_type, task_quadrant, time_block_category, circle, emotional_transaction_type, emotional_transaction_category, wellness_dimension, affirmation_frequency, badge_tier, points_type, partnership_status, contract_status, challenge_participant_status, coach_message_role.

5.3 V1 contract-backed tables#

Thirteen arete_v1_* tables store the V1 contract entities. Their column lists are exported as ARETE_CONTRACT_RECORD_COLUMNS and the table objects as ARETE_CONTRACT_RECORD_TABLES (keyed Habit, Goal, Routine, CheckIn, Journal, WeeklyReview, Plan, CoachingSummary, Streak, MissedDay, Friction, Intervention, Recovery).

The V1 enums (arete_v1_*, 20 enum types) mirror the contract enums in §4.1 and are listed in §4.1's value table.

5.4 Relations#

ALL_ARETE_RELATIONS exports Drizzle relations() definitions covering 55 tables. areteUsers is the hub: it declares many/one relations to missions, values, roles, goals, OKRs, habits, completions, streaks, journal entries, vision boards, tasks, plans, wellness logs, mood/sleep/energy entries, affirmations, achievements, the user level, points transactions, partnerships (both directions), commitment contracts (owner and referee), challenge participations, coach conversations/feedback, and all thirteen V1 record types. Foreign keys use onDelete: 'cascade' for owned data and onDelete: 'set null' for soft references (e.g. arete_vision_board_items.goal_id, arete_pomodoro_sessions.task_id, arete_commitment_contracts.referee).

5.5 Database automation (raw SQL exports)#

Three SQL blocks are exported as strings from db-schema.ts and are intended to be applied via migration. They encode the streak trigger, aggregation functions, and full-text search indexes respectively.

STREAK_CALCULATION_TRIGGER_SQL — defines the arete_update_streak_on_completion() PL/pgSQL function and the arete_streak_update_trigger (AFTER INSERT ON arete_habit_completions, FOR EACH ROW). The function logic proceeds as follows:

1. Skip rows where skipped = true — a recorded skip does not affect the streak.
2. Create a streak row for the habit if none exists yet.
3. Compute the day gap between the current insertion date and last_completion_date.
4. If the gap is 1 day (consecutive), increment current by 1.
5. If the gap is within the forgiveness window, consume a forgiveness day and increment.
6. If the gap exceeds the forgiveness window, reset current to 1.
7. Update best if current now exceeds it.
8. Write the new values back to both arete_streaks and the denormalized fields on arete_habits (current_streak, best_streak, total_completions).

STATISTICS_AGGREGATION_SQL — defines nine STABLE PL/pgSQL functions. Each function is optimized for the dashboard and coach aggregation queries:

JOURNAL_FULLTEXT_INDEX_SQL — creates two GIN indexes, arete_journal_entries_content_fts_idx and arete_journal_entries_title_fts_idx, both over to_tsvector('english', …).

5.6 Seed data — @arete/core/db-seed.ts#

db-seed.ts ships three sets of default data for initial database population. Each export ships its own Seed* interface (SeedJournalPrompt, SeedBadge, SeedLevel).

6. API Surface — apps/arete/api#

The API is a Fastify application. buildServer() (src/app.ts) assembles the instance; server.ts starts it. Routes are registered by registerRoutes() (src/routes/index.ts): health probes are unversioned; everything else is mounted under the /v1 prefix.

6.1 Plugins#

src/plugins/ registers plugins in the following order, each decorating the Fastify instance with domain-specific capabilities:

1. request-context — attaches per-request context for tracing and correlation IDs.
2. cors — configures cross-origin request handling.
3. error-handler — normalizes error responses to a consistent JSON shape.
4. swagger — serves OpenAPI documentation at /documentation.
5. auth — decorates fastify.authenticate using @fastify/jwt.
6. database — connects the pg pool and initializes the Drizzle client.
7. redis — initializes the ioredis client.
8. rate-limit — applies per-IP rate limiting.
9. mailer — configures nodemailer for transactional email.
10. repositories — registers per-domain repository modules (users, habits, goals, journal, vision, time, balance, gamification, coach).

6.2 Health routes (/health*, no auth)#

GET /health, GET /health/ready, GET /health/startup.

6.3 Users — /v1/users#

POST /register, POST /login, POST /logout, GET /me, PATCH /me, PATCH /preferences, GET /me/export, DELETE /me, POST /forgot-password, POST /reset-password, POST /change-password.

6.4 Habits — /v1/habits#

GET /, POST /, GET /today, GET /analytics, GET /:id, PATCH /:id, DELETE /:id, GET /:id/analytics, POST /:id/complete, GET /:id/completions, GET /:id/streak, GET /:id/recovery, POST /:id/friction/analyze, POST /:id/interventions/dispatch, POST /:id/stack.

The friction-analysis and intervention-dispatch endpoints are the V1 contract API — they operate on arete_v1_* tables and accept/return V1 contract schema types.

6.5 Goals — /v1/goals#

GET /, POST /, GET /analytics, GET /okrs, POST /okrs, GET /:id, PATCH /:id, DELETE /:id, POST /:id/progress, GET /:id/hierarchy.

6.6 Journal — /v1/journal#

GET /entries, POST /entries, GET /entries/:id, PATCH /entries/:id, DELETE /entries/:id, GET /prompts, GET /templates, GET /analytics.

6.7 Vision — /v1/vision#

GET /boards, POST /boards, GET /boards/:id, PATCH /boards/:id, DELETE /boards/:id, POST /boards/:id/items, GET /mission, PUT /mission, GET /values, PUT /values.

6.8 Time — /v1/time#

GET /tasks, POST /tasks, PATCH /tasks/:id, DELETE /tasks/:id, GET /weekly-plan, PUT /weekly-plan, GET /daily-plan/:date, PUT /daily-plan/:date, GET /pomodoro, POST /pomodoro/start, POST /pomodoro/complete.

6.9 Balance — /v1/balance#

GET /wheel-of-life, POST /wheel-of-life, GET /wheel-of-life/history, GET /mood, POST /mood, GET /mood/analytics, GET /sleep, POST /sleep, GET /energy, POST /energy.

6.10 Gamification — /v1/gamification#

GET /points, GET /points/transactions, GET /badges, GET /badges/available, GET /level, GET /leaderboards, GET /challenges, POST /challenges/:id/join, GET /accountability-partners, POST /accountability-partners/invite.

6.11 Coach — /v1/coach#

POST /chat, POST /chat/stream (SSE), GET /conversations, GET /recommendations, GET /insights, POST /feedback. The stream endpoint emits tokens at COACH_STREAM_INTERVAL_MS intervals using Server-Sent Events.

6.12 Dashboard — /v1/dashboard#

GET /summary, GET /weekly-activity, GET /recent-moods, POST /mood, GET /profile-stats.

6.13 API metadata#

GET /v1/info (authenticated) returns { name, version, description, environment, domains }, where domains lists habits, goals, journal, vision, time, balance, gamification, coach, affirmations, seven-habits.

7. Events#

The Arete domain does not publish a domain-event stream. There is no event bus, no emit/publish infrastructure, and no event-name constants in libs/arete/* or apps/arete/*. Cross-feature behaviour that would in other systems be event-driven (streak recalculation on completion) is instead handled synchronously by the PostgreSQL trigger in §5.5, and aggregation across features is handled by the dashboard and coach routes querying the database directly.

8. Configuration#

8.1 API environment variables — apps/arete/api/src/config.ts#

loadConfig() parses process.env with a Zod schema; missing values fall back to development defaults. A superRefine rejects the default JWT_SECRET in production and rejects DB_POOL_MIN > DB_POOL_MAX.

8.2 Library build configuration#

• Project tags (all libraries): ["scope:arete", "layer:domain", "type:lib"]
• Module format: ESM ("type": "module")
• Library build executor: @nx/js:tsc
• Library test executor: @nx/vite:test (per-library vitest.config.ts)
• @arete/api build/test/dev run via the nx:run-commands executor (tsc, vitest run, tsx watch src/server.ts)

9. Integration Points#

9.1 Internal dependencies#

The dependency boundaries are strict: no feature library imports another feature library. All cross-feature data access flows through the application layer or the database.

• Every personal-development feature library plus @arete/gamification and @arete/ai-coach depends on @arete/core (declared as a peerDependency).
• @arete/api depends on @arete/core, @arete/habits, @arete/ai-coach, and shared Oshun libraries (@oshun/auth, @oshun/errors, @oshun/logging, @oshun/metrics, @oshun/tracing).
• @arete/web depends on @arete/habits.
• @arete/core depends on @oshun/contracts for the V1 contract types used by the arete_v1_* tables.

9.2 Cross-domain references#

Arete couples to other Oshun domains at a single, well-defined point: the V1 friction-signal and intervention system. The V1 FrictionSignalSourceSchema names veritas, metis, tara, and nyx as domains that can publish friction signals into Arete's habit engine. The V1 InterventionKindSchema includes tara-ritual-surfacing and breathwork-insert as intervention types that surface practices from the Tara domain. Finally, @arete/habits/recovery exports a DEFAULT_TARA_RECOVERY_PRACTICE_REF constant so that Arete recovery prompts can surface a specific Tara practice. These are the only cross-domain couplings expressed in code — all other domain relationships described in the architecture document are conceptual, not code-level.

10. Acceptance Criteria#

A change to the Arete domain is consistent with this specification when all of the following conditions hold:

1. New entities are added as Zod schemas in @arete/core/schemas.ts (or as V1 contract schemas in @oshun/contracts/arete), with inferred types exported.
2. New persistent entities have a corresponding Drizzle table in db-schema.ts, registered in ALL_ARETE_TABLES, with relations registered in ALL_ARETE_RELATIONS and any new enum in ALL_ARETE_ENUMS.
3. New tables use the arete_ prefix and onDelete: 'cascade' for owned data.
4. New API endpoints are registered through registerRoutes() under /v1, carry a Fastify JSON schema, and require authentication unless deliberately public.
5. Streak-affecting writes go through arete_habit_completions so the streak trigger fires.
6. pnpm nx build, lint, and test pass for every affected project.