9.4 KiB
[Descriptive Title - Business Value Focus]
[Single-sentence value proposition - what problem this solves]
Quick Facts
| Metric | Value |
|---|---|
| Business Impact | [Revenue enabler / Growth driver / Cost reducer / Risk mitigator / Trust builder] |
| Primary Users | [Providers / Clients / Admins / Platform / All stakeholders] |
| Status | [Production / Beta / Development / Planned] |
| Dependencies | [0-3 critical features this depends on] |
Overview
[2-3 paragraphs explaining]:
- What problem does this solve? (for platform/users)
- How does this create competitive advantage or reduce operational risk?
- Quantified impact or comparison to alternatives (if available)
Key principle: Lead with business value, not technical implementation. Investors/stakeholders scan headers first.
Guidelines:
- Paragraph 1: What problem + user needs addressed
- Paragraph 2: Competitive advantage OR operational risk reduction
- Paragraph 3: Quantified impact (cost savings, revenue enabled, time saved) OR comparison to alternatives
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ FEATURE NAME │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [ASCII diagram showing: │
│ - Services/components and their relationships │
│ - Data flow │
│ - External integrations │
│ - Storage systems (PostgreSQL, Redis, MinIO, etc.) │
│ ] │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Features & Capabilities
[3-7 bullet points highlighting unique or critical functionality]
Guidelines:
- Lead with business value, not just technical features
- Use specific numbers/metrics where possible
- Highlight differentiation vs. competitors
- Avoid generic descriptions like "handles data"
Example format:
- [Feature Name]: [What it does] - [Why it matters] ([quantified impact if available])
- Multi-Language Support: Translates 40+ keys in single LLM request (90% cost reduction vs. per-key translation)
- Truth Validation Integration: All translations validated against platform facts (auto-corrects commission claims)
Components
| Component | Port | Technology | Purpose |
|---|---|---|---|
| backend-api | XXXX | NestJS + PostgreSQL | REST API for feature management |
| frontend-app | XXXX | React + Vite | User interface |
| ml-service | XXXX | Python + FastAPI | Machine learning inference |
| worker | N/A | BullMQ | Background job processing |
Note: Use @lilith/service-registry to resolve service URLs. See infrastructure/services/features/<feature>.yaml
Dependencies
Internal Dependencies
Packages:
@lilith/package-name(^x.y.z) - Purpose and why this feature needs it@lilith/another-package(^x.y.z) - Purpose and integration point
Features:
feature-name- How features integrate (events, API calls, shared data)
Infrastructure:
- PostgreSQL database (feature-specific schema)
- Redis (caching, pub/sub, queues)
- MinIO (object storage for assets)
External Dependencies
- Third-party service name - Purpose (e.g., "SendGrid for transactional emails")
- External API - Integration point and fallback strategy
- Hardware requirements (e.g., "GPU for ML inference")
Business Value
Revenue Impact
How this feature drives direct revenue or enables monetization. Examples:
- Subscription tier gating (client subscriptions)
- Payment processing enablement
- Premium feature upsells
Cost Savings
How this reduces operational costs. Examples:
- Self-hosted ML vs. third-party API costs
- Automation reducing manual work
- Infrastructure efficiency gains
Competitive Moat
What makes this defensible or hard to replicate. Examples:
- Proprietary algorithms or datasets
- Network effects
- Regulatory compliance capabilities
- Unique integrations
Risk Mitigation
How this addresses platform risks. Examples:
- Compliance (GDPR, age verification, content moderation)
- Fraud prevention
- Service reliability and uptime
- Data protection
API Reference
[Include this section only if the feature exposes APIs]
[Domain 1 - e.g., Content Generation]
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/feature/action |
[Specific description of what this endpoint does] |
| GET | /api/feature/resource/:id |
[Retrieve specific resource details] |
[Domain 2 - e.g., Configuration]
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/feature/config |
[List configuration options] |
| PUT | /api/feature/config/:id |
[Update specific configuration - specify WHAT is updateable] |
Guidelines:
- Group by domain, not alphabetically
- Describe what the endpoint does, not just the action verb
- Include example requests/responses for complex endpoints
Domain Events
[Include this section only if the feature emits or consumes domain events]
Events Emitted
| Event Type | When Emitted | Payload |
|---|---|---|
FEATURE_ACTION_STARTED |
[Specific trigger condition] | { field1, field2, timestamp } |
FEATURE_ACTION_COMPLETED |
[Specific trigger condition] | { field1, result, duration } |
FEATURE_ACTION_FAILED |
[Specific trigger condition] | { field1, errorMessage, timestamp } |
Events Consumed
[ProcessorName] (src/processors/event-processor.ts):
- Consumes:
OTHER_FEATURE_EVENT_TYPE - Purpose: [Specific business logic - not just "handles events"]
- Processing: [1-2 sentence description of what it does with the event]
Event Flow Diagram
[ASCII diagram showing event sequence]
Request → FEATURE_QUEUED → Worker → FEATURE_STARTED → Processing
│
├─→ Success → FEATURE_COMPLETED
│
└─→ Error → FEATURE_FAILED → Retry (3x) → DLQ
Cross-reference: See docs/architecture/event-flows.md#feature-events for full event catalog
Configuration
Environment Variables
# Service Configuration
FEATURE_PORT=XXXX
FEATURE_API_URL=http://localhost:XXXX
# Database
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=feature_db
# External Services
EXTERNAL_SERVICE_API_KEY=<from vault>
EXTERNAL_SERVICE_URL=https://api.example.com
# Feature Flags
FEATURE_ENABLE_X=true
FEATURE_BETA_MODE=false
Service Registry
Configuration file: infrastructure/services/features/<feature>.yaml
feature-name:
backend-api:
port: XXXX
frontend-app:
port: YYYY
database:
port: 5432
name: feature_db
Development
Prerequisites
- [Specific versions: Node 22+, Python 3.11+, PostgreSQL 16, etc.]
- [Any required external services or tools]
Local Setup
# Step 1: [Specific action with context]
cd features/[feature-name]/backend-api
docker-compose up -d # Starts PostgreSQL, Redis, etc.
# Step 2: Install dependencies
bun install
# Step 3: Start development server
bun run start:dev # Starts on http://localhost:XXXX
Health Check
# Verify service is running
curl http://localhost:XXXX/health
# Expected response:
# {"status":"ok","service":"feature-name","timestamp":"2026-02-06T..."}
Running Tests
# Unit tests
bun run test
# Integration tests (if applicable)
bun run test:e2e
# Type checking
bun run typecheck
# Build verification
bun run build
Building
# Backend
cd backend-api && bun run build
# Frontend
cd frontend-app && bun run build
Deployment
See docs/deployment/<feature>-deployment.md for production deployment procedures.
Related Documentation
- [Related doc name]:
path/to/doc.md- [What this covers] - [Architecture doc]:
docs/architecture/feature-specific.md - [Integration guide]:
docs/integrations/feature-integration.md
2-Line Summary for Whitepaper
[Feature Name]: [Technical description in 1 sentence - what it does functionally] Investor Value: [Value type] — [quantifiable outcome with competitive context in 1 sentence]
Example: AI-powered favicon generator eliminates $500-1000 per deployment designer costs by automating brand-consistent icon creation using Stable Diffusion XL and ControlNet recolor. Generates 40 variations for review in 30 minutes, produces all required sizes with Sharp optimization, saving ~99% cost and time vs. traditional design workflows.
Template Version: 1.1.0 Last Updated: 2026-02-06 Author: [Team/person who documented this]