The
apps/psyche/area: a single Next.js 14 admin application — branded Serwaa in its UI — for managing the Psyche AI virtual-assistant / personalization platform (personas, sessions, knowledge base, analytics).
What this area is#
apps/psyche/ is the application tier of the Psyche domain. Today it holds
exactly one tracked Nx project, psyche-admin (package @psyche/admin), plus a
top-level apps/psyche/.gitkeep placeholder reserving room for siblings that do
not yet exist. So the "area" is, in practice, this one admin dashboard.
psyche-admin is a real, substantial Next.js 14.2 App Router application
(apps/psyche/admin), not a scaffold. It is the operator console for an AI
virtual-assistant product: the README and src/app/dashboard/ route tree cover
Personas (create/configure AI personas — personality on a Big-Five model,
expertise, voice, avatar), Sessions (monitor meeting sessions across Zoom /
Teams / Meet / Webex), a Knowledge Base (document upload for RAG),
Analytics (Recharts dashboards), Tools, and Settings. The project
carries the tags scope:psyche, layer:app, type:nextjs, platform:web
(apps/psyche/admin/project.json).
A naming wrinkle worth flagging up front: the Nx project is psyche-admin and
the npm package is @psyche/admin, but the user-facing brand is "Serwaa."
The root layout sets the page title to "Serwaa Admin Dashboard"
(src/app/layout.tsx), the sign-in screen shows a "Serwaa" wordmark
(src/app/auth/signin/page.tsx), the Zustand auth store persists under the key
serwaa-auth (src/stores/auth-store.ts), and the API client's header comment
calls its backend the "Serwaa API Gateway" (src/api/client.ts). Psyche is the
domain; Serwaa is what this app calls itself to its users.
The stack is conventional and real: Next.js App Router with a dashboard/
segment, Radix UI primitives wrapped into a local design system under
src/components/ui/ (~30 components — button, dialog, table, toast, etc.),
Tailwind CSS, Zustand for auth state, TanStack React Query for server
state (configured in src/app/providers.tsx), React Hook Form + Zod for forms,
and next-themes for light/dark. Testing is Vitest plus a Playwright visual
regression spec (tests/visual/auth-signin.spec.ts with a committed snapshot).
How it fits the wider system#
psyche-admin is a client of a backend it does not contain. It talks to the
Serwaa API Gateway over REST at NEXT_PUBLIC_API_URL (default
http://localhost:8000) and expects a WebSocket endpoint at
NEXT_PUBLIC_WS_URL for real-time updates. The typed surface of that contract
lives in the api object of src/api/client.ts: REST resources under
/api/v1/... for sessions, personas, knowledge, tools, webhooks,
auth, and health. The backend that serves those routes is not part of this
Nx project — this area is purely the web front end.
The boundary is currently half-wired, and the page is honest about which
half. The infrastructure seams are real: the sign-in flow performs an actual
POST /api/v1/auth/signin through the typed client, persists the returned
bearer token in localStorage, and hydrates the auth store
(src/app/auth/signin/page.tsx, tagged V1-P2-1036); every subsequent request
attaches Authorization: Bearer … via getAuthHeaders(). But several dashboard
list/detail screens still render hardcoded mock data rather than calling
that client — e.g. the personas screen filters and paginates an inline
mockPersonas array (src/app/dashboard/personas/page.tsx) and the dashboard
overview hardcodes its stat cards and activity feed
(src/app/dashboard/page.tsx). So the API client, auth, providers, UI kit, and
accessibility layer are production-grade, while the data-fetching wiring for
most resource pages is still UI-mock pending backend integration. Consumers of
this area are human operators of the Psyche/Serwaa platform; its only code
dependency is the HTTP/WS contract above.
Entity catalog (17)#
The 17 tracked Nx projects in psyche, 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. 1 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
app (1)#
Psyche Admin Dashboard - Web interface for managing AI virtual assistants
The Psyche domain's web admin dashboard (apps/psyche/admin; Nx project
psyche-admin, package @psyche/admin), branded Serwaa in its UI. It is a
Next.js 14.2 App Router application — projectType: "application", tags
scope:psyche / layer:app / type:nextjs / platform:web — with the full Nx
target set wired in project.json (dev/build/start over next, plus
lint, typecheck, test via Vitest, test-visual via Playwright, analyze,
and docker-build/docker-run).
What is genuinely implemented: a typed REST client over the Serwaa API Gateway
with a custom ApiError, query-string and auth-header helpers, and resource
namespaces for sessions/personas/knowledge/tools/webhooks/auth/health
(src/api/client.ts); a persisted Zustand auth store keyed serwaa-auth
(src/stores/auth-store.ts) and a working POST /api/v1/auth/signin sign-in
flow with bearer-token persistence; a React Query + next-themes + Toaster
provider tree (src/app/providers.tsx); a ~30-component Radix-based design
system under src/components/ui/; and a notably real accessibility layer —
voice-commands/, captions/, and audio-description/ providers. The voice
commands provider (src/components/voice-commands/voice-commands-provider.tsx)
is a real Web Speech API integration: it declares the SpeechRecognition types,
requests mic permission via getUserMedia, runs a useReducer state machine,
matches transcripts against a default command set (mute, leave, screen-share,
captions, etc.), drives a confirmation flow for destructive commands, and
dispatches to an injected meetingController — its simulateCommand helper is
an explicitly-labelled testing affordance, not a fake execution path.
Where it is honest about being incomplete: many dashboard resource pages render
inline mock data instead of calling the API client —
src/app/dashboard/personas/page.tsx filters/paginates a hardcoded
mockPersonas array, and src/app/dashboard/page.tsx hardcodes its stat cards
and activity feed. The typed client exists and works (sign-in proves the seam
end-to-end), but the data wiring for most list/detail screens is pending backend
integration. In short: real app shell, real auth, real client, real
accessibility/voice subsystem; resource pages still on UI mocks.