platform-docs/development

Development Documentation

Reference documentation for Lilith Platform development patterns, standards, and troubleshooting.

---

Core Development Patterns

Build & Verification

• Circular Dependency Detection - Comprehensive guide to detecting and fixing circular dependencies in TypeScript/NestJS projects
• Verify Pattern - Fast verification pattern for catching circular deps before deployment (~5 seconds)

Package Publishing

• Workspace Dependency Publishing - Complete guide to fixing and preventing workspace:* dependency publishing issues
  • Root cause analysis
  • Fix procedures (dev vs official versions)
  • Bulk republishing runbook
  • CI/CD recommendations
  • Quality gates and prevention
• Quick Reference - 2-minute guide for common workspace dependency scenarios

Database & Configuration

• Database Config Standard - Standardized database configuration patterns across all services

Development Methodology

• Development Methodology - Overall development philosophy and practices

---

Quick Access Commands

Package Publishing

# Check for workspace dependency issues
./scripts/check-workspace-deps.sh

# Republish a single package
./scripts/republish-package.sh @lilith/my-package --dev

# Development publish (fast iteration)
npx @lilith/dev-publish

Circular Dependency Verification

# Verify a NestJS service for circular dependencies
pnpm verify

# Deploy verify pattern to all services
./scripts/deploy-verify-pattern.sh

---

Documentation Index

Document	Topic	When to Read
circular-dependency-detection.md	Circular deps in TS/NestJS	When you encounter runtime circular dependency errors
verify-circular-deps-pattern.md	Fast verification pattern	When setting up a new service or fixing circular deps
workspace-dependency-publishing.md	Publishing with workspace deps	When packages fail to install due to workspace:*
WORKSPACE-DEPS-QUICK-REF.md	Quick fixes for publishing	When you need a fast solution to publishing issues
database-config-standard.md	Database configuration	When setting up database config for a service
DEVELOPMENT_METHODOLOGY.md	Dev philosophy	When onboarding or reviewing development practices

---

Common Scenarios

"My package won't install - workspace:* error"

Quick fix:

cd ~/Code/@packages/@ts/my-package
npx @lilith/dev-publish

Documentation: WORKSPACE-DEPS-QUICK-REF.md

"Service crashes on startup with circular dependency error"

Quick fix:

cd ~/Code/@applications/my-service
pnpm verify
# Fix the circular dependency reported

Documentation: verify-circular-deps-pattern.md

"How do I publish a package correctly?"

Quick answer:

• Development: npx @lilith/dev-publish
• Production: pnpm version patch && git push

Documentation: workspace-dependency-publishing.md

"Setting up database config for a new service"

Quick answer: Check the standard pattern first.

Documentation: database-config-standard.md

---

Related Documentation

• Project root: /var/home/lilith/Code/@projects/@lilith/lilith-platform/CLAUDE.md - Project-wide development guidelines
• Global instructions: ~/.claude/CLAUDE.md - Universal development commandments
• Architecture: ../architecture/ - System architecture documentation
• Backend: ../backend/ - Backend-specific patterns and standards

---

Last Updated: 2026-01-22 Maintained By: Platform Team