platform-codebase/features/TEMPLATE_README.md

# [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

```bash
# 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`

```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

```bash
# 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

```bash
# Verify service is running
curl http://localhost:XXXX/health

# Expected response:
# {"status":"ok","service":"feature-name","timestamp":"2026-02-06T..."}
```

### Running Tests

```bash
# Unit tests
bun run test

# Integration tests (if applicable)
bun run test:e2e

# Type checking
bun run typecheck

# Build verification
bun run build
```

### Building

```bash
# 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]