# Arete — Systems Deep Dive

> The `apps/arete/` area: three deployable applications — a Fastify REST API, a
> Vite/React web dashboard, and an Expo/React Native mobile app — that together
> ship **Arete**, the personal-development product modelled on Stephen Covey's
> "7 Habits of Highly Effective People."

## What this area is

Arete is a self-improvement product: members track habits, set and progress
goals, journal, run "Wheel of Life" balance check-ins, manage time, earn
gamification rewards, and talk to an AI coach. `apps/arete/` holds the three
client-facing applications that deliver that product across surfaces. They are
the `scope:arete` apps in the monorepo — distinct from the shared `@arete/*`
**libraries** (`@arete/core`, `@arete/ai-coach`, `@arete/habits`) that live
outside this directory and that the API composes.

`@arete/api` is the spine. Its `buildServer()` factory
(`apps/arete/api/src/app.ts`) assembles a Fastify instance with a deliberate
plugin order — request-context → CORS → error-handler → Swagger → auth (JWT) →
database (PostgreSQL + Drizzle) → Redis → rate-limit → mailer → repositories →
routes. Routes are grouped by domain under `/v1/*` (`habits`, `goals`,
`journal`, `vision`, `time`, `balance`, `gamification`, `coach`, `dashboard`,
`reminders`) and registered in `apps/arete/api/src/routes/index.ts`. The domain
logic reaches storage through a repository seam (`fastify.repositories.*`):
Drizzle/Postgres-backed in production, in-memory in tests. The AI coach routes
delegate to the `@arete/ai-coach` library for deterministic CBT prompting,
recommendations, and per-user pattern detection over the member's real records.

`@arete/web` and `@arete/mobile` are the two consumer front-ends over that API.
The web app (`apps/arete/web/src/router.tsx`) is a React Router SPA with
lazy-loaded, auth-gated pages for every domain (dashboard, habits, goals,
journal, time, wellness, vision, analytics, coach, settings, profile), a
fetch-based API client with token refresh (`apps/arete/web/src/api/client.ts`),
React Query hooks, Zustand stores, and a large in-repo component library
(charts, tables, forms, ~50 UI primitives). The mobile app
(`apps/arete/mobile/App.tsx`) is a React Native client with stack + bottom-tab
navigation (`src/navigation/AppNavigator.tsx`), React Query, offline-sync and
push-notification services, biometric/social login, and native home-screen
widgets for iOS (`ios/AreteWidgets/`) and Android (`android/.../widgets/`).

## How it fits the wider system

The three apps relate front-end-to-back-end, not as a library graph:
`@arete/web` and `@arete/mobile` are independent clients that call `@arete/api`
over HTTP. The API in turn integrates **upward** into the Oshun platform through
a dedicated service-to-service facade,
`apps/arete/api/src/routes/oshun-facade.ts`. That plugin serves `/v1/oshun/*`
(and the `/v1/arete/healthz` probe) for the Oshun BFF's Arete adapter to dial:
it maps Arete's repository records onto the canonical `@oshun/domain-arete` wire
shapes, wraps every response in the `@oshun/contracts` partial-failure envelope
(`{ results, errors, partial }`), fails closed on a missing/invalid
`ARETE_OSHUN_FACADE_TOKEN` in production, and bridges opaque Oshun member ids to
shadow `arete_users` rows so facade writes land in the same tables the native
`/v1/*` routes read. The API also depends on shared platform libraries
(`@oshun/auth`, `@oshun/database`, `@oshun/errors`, `@oshun/logging`,
`@oshun/metrics`, `@oshun/tracing`) and the Arete domain libraries
(`@arete/core` schema, `@arete/ai-coach`, `@arete/habits`). The boundary is
clean: the front-ends never import the API's internals, and the Oshun platform
integrates only through the facade contract, never the native routes.

## Entity reference

### @arete/api

The Fastify REST backend for Arete (`apps/arete/api`,
`projectType: application`, tags `scope:arete` / `type:app` / `layer:service`).
`src/app.ts` exports `buildServer()`, which registers eleven plugins in a
dependency-correct order and then all route groups; `src/server.ts` is the
separate entry point that actually `.listen()`s. This is a fully implemented
service, not a scaffold: real domain routes for habits, goals, journal, vision,
time, balance, gamification, AI coaching, dashboard aggregation, and reminder
production, each backed by a repository seam (`src/repositories/*.ts`) that is
Drizzle/Postgres-backed in production and memory-backed in tests, with broad
`__tests__/` coverage and an `e2e/arete-v1-flows.e2e.test.ts`. The coach routes
(`src/routes/coach.ts`) compose the `@arete/ai-coach` library for CBT prompting
and pattern detection, and `src/routes/oshun-facade.ts` adds the `/v1/oshun/*`
service-to-service surface the Oshun BFF consumes. It depends on the shared
`@oshun/*` platform libraries and the `@arete/core` / `@arete/habits` domain
libraries.

### @arete/web

The Vite/React web dashboard (`apps/arete/web`, tags `scope:arete` / `type:app`
/ `platform:web`), built and served via the `@nx/vite` executors. It is a fully
built-out SPA: `src/router.tsx` defines an auth-gated route tree with
eagerly-loaded auth pages and lazy-loaded, `ProtectedRoute`-wrapped pages for
dashboard, habits, goals, journal, time, wellness, vision, analytics, coach,
settings, and profile. `src/api/client.ts` is a fetch client with automatic
auth-token injection and a 401 auto-refresh flow; domain data flows through
React Query hooks (`src/api/hooks/*`) and Zustand stores (`src/stores/*`). The
package carries a substantial in-repo design system — chart components
(`src/components/charts/`), a `DataTable` and form kit, and roughly fifty UI
primitives under `src/components/ui/` — plus Vitest unit tests and Playwright
e2e specs (`e2e/*.spec.ts`, including grace-window and humane-streak-copy
flows). It is a client of `@arete/api`, not a dependency of it.

### @arete/mobile

The Expo/React Native mobile app (`apps/arete/mobile`, tags `scope:arete` /
`type:app` / `platform:mobile`), with `nx:run-commands` targets for Metro
(`react-native start`), Android/iOS run and release builds, Jest tests, and an
e2e target. `App.tsx` is the real entry point: it wires `SafeAreaProvider`,
`GestureHandlerRootView`, and a React Query `QueryClientProvider`, then
bootstraps `PushNotificationService`, `OfflineSyncService`, the app store, and
session restore before rendering `AppNavigator`. Navigation
(`src/navigation/AppNavigator.tsx`) switches between an auth stack and main
bottom-tabs, with per-domain stacks for habits, goals, journal, vision, time,
balance, gamification, coach, and settings — each with multiple implemented
screens (e.g. creation wizards, analytics, habit-stacking, OKR, Wheel-of-Life)
under `src/screens/`, alongside a shared component library and domain hooks. It
also ships native home-screen widgets — Swift `ios/AreteWidgets/` (Today /
LockScreen) and Kotlin `android/.../widgets/` (Streak, HabitProgress). This is a
real application; the in-repo `JEST_FAILURES.md` and `IOS_XCODEPROJ.md` notes
flag known test/build-config gaps honestly. Like the web app, it is a client of
`@arete/api`.