MIRRORSTATE

Behavioral enforcement operating system — quantified identity, operational evidence, no self-deception

Local validation: pnpm run ci — root ESLint, Turborepo lint · typecheck · test · build across the graph.

Architecture · Implementation spec · UI systems · Visual principles · ADR index

---

Table of contents

• Why MIRRORSTATE exists
• What ships in this repository
• Topology at a glance
• Monorepo map
• Applications
• Packages
• Web routes (App Router)
• Prerequisites
• Quick start
• Scripts
• Environment & infra
• Quality bar
• Documentation
• Architecture decision records
• Philosophy & boundaries

---

Why MIRRORSTATE exists

North star: What should you be doing right now?

MIRRORSTATE is a behavioral mirror, quantified identity engine, and operational execution system — designed for cold, evidence-based confrontation with declared versus observed behavior. It is not a productivity cheerleader, habit gamifier, or wellness product.

System affect: precise, observant, inevitable — never inspirational or therapeutic in tone.

The full product charter, psychological primitives, Standing / Integrity / Reputation triad, Tribunal mechanics, analytics boundaries (deterministic only — no generative AI), and database philosophy live in docs/ARCHITECTURE.md. This README stays navigational; depth belongs in docs.

---

What ships in this repository

Layer	Role
Web shell	Next.js App Router — institutional command surfaces, narrative URL focus, forensic timeline, archival flows, realtime client
API	Fastify control plane — HTTP, Swagger, Socket.IO, domain orchestration, queue producers
Worker	BullMQ consumers — background operational workloads
Packages	Contracts (Zod), domain core/application, engines (temporal, timeline, analytics, tribunal, events), DB + Prisma, auth, config, design tokens, copy registry, operational mock / replay

---

Topology at a glance

flowchart LR
  subgraph clients [Clients]
    WEB[Next.js App Router]
  end
  subgraph edge [Edge / local]
    NGINX[Nginx]
  end
  subgraph compute [Compute]
    API[Fastify API]
    SIO[Socket.IO]
    WRK[BullMQ worker]
  end
  subgraph data [Data]
    PG[(PostgreSQL)]
    RD[(Redis)]
  end
  WEB --> NGINX
  NGINX --> API
  NGINX --> SIO
  API --> PG
  API --> RD
  SIO --> RD
  WRK --> PG
  WRK --> RD

Loading

For Nginx, Compose layouts, tunnel notes, and deployment narrative, see docs/IMPLEMENTATION_SPEC.md (section 15 — Deployment architecture) and infra/ (compose, Docker, nginx, Cloudflare tunnel doc).

---

Monorepo map

Actual workspace layout (high signal — not every file):

mirrorstate/
├── apps/
│   ├── api/                 # Fastify + Socket.IO + BullMQ producers
│   ├── web/                 # Next.js 15 — App Router, Tailwind, Vitest
│   └── worker/              # BullMQ consumers (pino, Redis)
├── packages/
│   ├── analytics-engine/
│   ├── auth/
│   ├── command-bus/
│   ├── config/
│   ├── contracts/           # Zod DTOs + shared types (+ domain-language, operational-mock)
│   ├── copy-registry/       # Behavioral copy keys — institutional tone
│   ├── db/                  # Prisma schema, migrations, projections CLI
│   ├── design-tokens/
│   ├── domain-application/
│   ├── domain-core/
│   ├── domain-language/
│   ├── event-engine/
│   ├── operational-mock/    # Deterministic replay, forensic bundles, report engine
│   ├── temporal/
│   ├── timeline-engine/
│   └── tribunal-engine/
├── tooling/
│   └── eslint-config/
├── infra/                   # docker, compose, nginx, env.example, tunnel docs
├── docs/                    # ARCHITECTURE, IMPLEMENTATION_SPEC, ADRs, UI + visual specs
├── package.json
├── pnpm-workspace.yaml
└── turbo.json

Rationale for pnpm + Turborepo: docs/adr/001-monorepo-structure.md.

---

Applications

App	Package	Tech	Scripts
Web	@mirrorstate/web	Next 15, React 19, Tailwind 3, PostCSS, Framer Motion, TanStack Query, Zustand, Socket.IO client, Vitest	dev → :3000, build, start, lint, typecheck, test
API	@mirrorstate/api	Fastify 5, @fastify/cors / swagger / swagger-ui, Socket.IO, BullMQ, ioredis, pino, Zod, tsx	dev (watch), build → dist, start, lint, typecheck
Worker	@mirrorstate/worker	BullMQ, ioredis, pino, tsx	dev, build, start, lint, typecheck

---

Packages

Package	Purpose
@mirrorstate/contracts	Shared Zod schemas and DTO surfaces across HTTP/WS/domain
@mirrorstate/domain-language	Ubiquitous language types / helpers
@mirrorstate/domain-core	Core domain model + tests (Vitest)
@mirrorstate/domain-application	Application layer / use-case orchestration
@mirrorstate/command-bus	Command routing + validation glue
@mirrorstate/event-engine	Event taxonomy and envelopes
@mirrorstate/temporal	Operational time, windows, drift — temporal semantics
@mirrorstate/timeline-engine	Timeline projections
@mirrorstate/analytics-engine	Deterministic analytics (no LLM pipeline)
@mirrorstate/tribunal-engine	Standing order, volatility, witness-oriented mechanics
@mirrorstate/db	Prisma client + migrations + projection rebuild CLI
@mirrorstate/auth	JWT / session helpers for the API surface
@mirrorstate/config	Typed configuration
@mirrorstate/design-tokens	Visual system inputs for the web shell
@mirrorstate/copy-registry	Institution-grade copy — tested registry
@mirrorstate/operational-mock	Mock seed, forensic replay, report/casefile assembly, JSON export — deterministic tests
tooling/eslint-config	Shared ESLint flat config for the monorepo

---

Web routes (App Router)

Route	Surface (illustrative)
/	Entry / shell
/command	Command center
/timeline	Forensic timeline + narrative focus
/exposure	Exposure dossier
/analytics	Analytics / forensics
/standing	Standing reserve
/integrity	Integrity diagnostics
/tribunal	Tribunal / witness pressure
/reputation	Long-horizon reputation
/contracts	Contract theater
/feed	Operational feed
/reports	Institutional reports
/archive	Archival casefile
/investigate	Custom investigation windows
/settings	Settings

Deep behavior (URL ?focus= codec, narrative bridge, replay-backed UI) is covered in code under apps/web and bounded-context detail in docs/ARCHITECTURE.md / docs/UI_SYSTEMS_BLUEPRINT.md — avoid duplicating those chapters here.

---

Prerequisites

• Node.js >= 20.18.0 (package.json engines)
• pnpm 9.15.0 (see packageManager field — use Corepack or matching pnpm)
• PostgreSQL and Redis when running API/worker against real infra (local defaults documented in infra/env.example and implementation spec)

---

Quick start

# Install dependencies
pnpm install

# Full CI-style gate (recommended before push)
pnpm run ci

Develop individual apps (from repo root):

pnpm --filter @mirrorstate/web dev
pnpm --filter @mirrorstate/api dev
pnpm --filter @mirrorstate/worker dev

Database (when wired to Prisma workflows):

pnpm run db:generate
pnpm run db:migrate

---

Scripts

Script	What it does
pnpm run build	turbo run build — DAG-respecting package then app builds
pnpm run dev	turbo run dev — parallel persistent dev tasks
pnpm run lint	Root eslint . and turbo run lint
pnpm run typecheck	turbo run typecheck
pnpm run test	turbo run test
pnpm run ci	lint + typecheck + test + build — merge-ready bar
pnpm run format / format:check	Prettier write / check
pnpm run db:*	Prisma generate / migrate / push via @mirrorstate/db

---

Environment & infra

Asset	Location
Example env	infra/env.example
Compose	infra/compose/docker-compose.yml
Dockerfiles / nginx	infra/docker/, infra/nginx/
Tunnel notes	infra/CLOUDFLARE_TUNNEL.md

Production topology, observability, and security architecture: docs/IMPLEMENTATION_SPEC.md.

---

Quality bar

Concern	Stack
Typing	TypeScript 5.7 strict presets across packages
Lint	ESLint 9 flat config (@eslint/js, typescript-eslint)
Formatting	Prettier 3
Git hooks	Husky + lint-staged
Commits	Commitlint — conventional preset
Tests	Vitest in applicable packages (e.g. web, operational-mock, domain-core, engines)
API docs	Fastify Swagger + Swagger UI (@fastify/swagger, @fastify/swagger-ui)

---

Documentation

Document	Contents
docs/ARCHITECTURE.md	North star, triad model, bounded contexts, schema narrative, realtime, security, full blueprint
docs/IMPLEMENTATION_SPEC.md	Phase-2 execution spec: events, APIs, temporal, analytics engine, pressure, copy registry, deployment
docs/UI_SYSTEMS_BLUEPRINT.md	Frontend operational architecture — shell, routes, state, pressure matrix
docs/visual-principles.md	Density, motion restraint, asymmetry, pressure-state composition
docs/IMPLEMENTATION_SPEC.md#18-adr-index-architecture-decision-log	ADR index inside the spec (cross-link)

---

Architecture decision records

ADR	Topic
001 — Monorepo structure	Turborepo + pnpm workspaces
002 — Standing ledger philosophy	Reserve ledger semantics
003 — WebSocket strategy	Realtime transport
004 — State ownership	Where truth lives
005 — Design token immutability	Tokens as contracts
006 — Event-driven architecture	Events & projections

---

Philosophy & boundaries

• Deterministic analytics only — classical / rule-driven / explainable pipelines. No LLM product surface, no generative coaching copy.
• Copy discipline — banned roots (e.g. productivity-motivation idioms) enforced via contracts / registry; see ARCHITECTURE and packages/contracts.
• Standing is not gamification — public operational reserve, not XP or karma framing.

For the authoritative vocabulary list, monetization firewall, and psychological levers, read docs/ARCHITECTURE.md (sections 1–2 and bounded contexts).

---

Built with institutional rigor — read the docs, run pnpm run ci, ship honestly.

_{README navigates; ARCHITECTURE.md explains.}