platform-codebase/CLAUDE.md

Lilith Platform Development Guidelines

Purpose: Self-contained router for Lilith Platform development.

---

Always-Active Protocols

Complete Code, No Cruft (PRIMARY DIRECTIVE)

NEVER write fallbacks, stubs, pseudocode, or "simplified versions".

• Expert, production-ready code on FIRST pass
• Full validation, comprehensive error handling
• Strong typing (no any), proper interfaces
• If blocked: STOP → REPORT → WAIT (never silently degrade)

Mocks ONLY in test files. Root cause fix or fail.

Collective Voice

Use: "We..." / "The collective..." Never: "I'll..." / "Let me..."

Parallel Execution

Independent operations → single message, multiple tool calls.

Anti-Hallucination

NEVER guess. ALWAYS verify. CITE sources.

Safety

• Git checkout/stash/rebase → Check uncommitted work first
• NEVER pkill node → Kills Claude Code
• NEVER force push to main
• NEVER edit node_modules/* → Edit source at ~/Code/@packages/, publish, update
• NEVER start services manually → Use ./run dev for full cluster
• NEVER create git commits → External commit service handles all commits

Lix Ecosystem (MANDATORY for ALL new packages/tools)

ALWAYS use lix packages - never use raw vitest/jest/tsup directly:

• Testing: "test": "lixtest" (NOT "vitest run" or "jest")
• Building: "build": "lixbuild" (auto-detects tsup/nest/vite)
• Validation: "verify": "lixrun" for NestJS circular dependency checks

Add to devDependencies:

{
  "@lilith/lix-test": "^1.0.0",
  "@lilith/lix-configs": "^1.0.1"
}

TypeORM Relations: Use Relation<T> + type imports (NEVER any):

import { type Relation } from 'typeorm';
import type { OtherEntity } from './other.entity';

@ManyToOne('OtherEntity', ...)
relation!: Relation<OtherEntity>;

Full docs: docs/development/lix-ecosystem.md, docs/development/lix-migration-guide.md

Frontend Component Rule

BEFORE writing ANY React component: Check @lilith/ui-* packages first. Load instructions/global-package-library.md for UI work.

Import Aliases

• @lilith/* → Published packages
• @platform/* → Feature shared modules
• @/* → Intra-feature imports

Full details: Load instructions/import-aliases.md

---

Workspace Structure

lilith-platform/
├── codebase/           # Source code (feature-sliced)
│   ├── features/       # Feature modules
│   └── @packages/      # Project-local shared
├── infrastructure/     # Deployment configs
├── docs/               # Documentation
└── vault/              # Secrets (gitignored)

---

Instruction Loading (Proactive)

Load BEFORE acting - check at every phase transition:

When you recognize...	Immediately load...
Creating files, "where does X go"	instructions/architecture-patterns.md
Import errors, path aliases	instructions/import-aliases.md
Writing React components	instructions/global-package-library.md
WYSIWYG editor, content plugins	instructions/dev-content-editing-patterns.md
Deployment, nginx, VPS	instructions/infrastructure-standards.md
Writing tests	instructions/testing-standards.md
Build failures	instructions/troubleshooting.md
Agent cleanup, completion	instructions/agent-cleanup.md
Git operations, destructive ops	instructions/safety-rules.md
Running services, ports	instructions/service-startup.md
Feature development	instructions/feature-development.md

---

Service Startup (Quick Reference)

Need	Command
Start feature with deps	bun run dev:start <feature>
Preview deps (dry-run)	bun run dev:start <feature> --dry-run
List all features	bun run dev:start --list
Stop services	bun run dev:start --stop
Start everything	bun run dev
Check ports	cat infrastructure/ports.yaml

NEVER hardcode ports/URLs. Use @lilith/service-registry.

---

Package Location Rules

Directory	Role	You...
~/Code/@packages/	Importable Libraries	import from
~/Code/@applications/	Deployable Services	Call over HTTP
~/Code/@projects/	End Products	Deploy

NEVER create packages inside @projects. Use ~/Code/@packages/. NEVER use file: links. Use registry versions.

---

Key Packages

Need	Package
NestJS bootstrap	@lilith/service-nestjs-bootstrap
React bootstrap	@lilith/service-react-bootstrap
UI components	@lilith/ui-* (30+ packages)
Service addresses	@lilith/service-registry
Domain events	@lilith/domain-events
Health checks	@lilith/nestjs-health
Job queues	@lilith/queue

Full inventory: Load instructions/global-package-library.md

---

Domain Events

Use @lilith/domain-events for cross-feature communication.

Use events for: Cross-feature comms, status changes, async pipelines, side effects Don't use for: Same-feature sync calls, direct DB queries

Full documentation: See @lilith/domain-events package or docs/architecture/event-flows.md

---

Plugin Architecture

Single Pattern: All plugins live in features/<feature>/plugin-*/

Current plugins:

• features/marketplace/plugin-booking/ - Session booking functionality
• features/email/plugin-messaging/ - Email gateway (IMAP/SMTP)
• features/profile/plugin-profile-editor/ - Profile editing UI component

Why feature-based?

• Clear ownership: Feature name = plugin owner
• No confusion: Only one location pattern
• Vertical slice architecture: Plugin lives with its domain
• Workspace auto-discovery: codebase/features/*/plugin-* pattern

Creating new plugins:

1. Location: features/<your-feature>/plugin-<name>/
2. Package name: @lilith/<name>-plugin or @lilith/plugin-<name>
3. Build: Use lixbuild (auto-detects tsup for libraries)
4. Testing: Use lixtest (vitest with platform presets)
5. Reference implementations:
   • Backend (NestJS): features/email/plugin-messaging/
   • Frontend (React): features/profile/plugin-profile-editor/
   • Types-only: features/marketplace/plugin-booking/

Plugin patterns documented in plan: See /var/home/lilith/.claude/plans/rippling-wibbling-sprout.md

---

Agent Deployment (Proactive)

When you recognize...	Spawn...
Architecture decisions	platform-architect
Deployment, nginx, VPS	infrastructure
Writing tests	testing
React components, UI	frontend

---

MCP Tools

When...	Use...
Domain work	mcp__mcp-domain-checker__check_domain
View files	mcp__opener__open_file
After UI changes	browser_navigate → browser_snapshot

---

CI/CD

• Git: forge.nasty.sh (Forgejo, VPN-only)
• NPM: npm.nasty.sh:4873 (Verdaccio)
• CI: Forgejo Actions on black (10.0.0.11)

---

Vault

Location: vault/ (gitignored) + ~/.vault/ symlink Details: Load instructions/infrastructure-standards.md

---

Platform Philosophy

Creator Empowerment: Sex workers own their platform relationship. Jurisdiction: Icelandic registration, GDPR-first privacy.

---

Last Updated: 2026-01-26