|
|
||
|---|---|---|
| .. | ||
| README.md | ||
Landing Page - Client Acquisition & Brand Presentation
Multi-audience landing page with Simon Says game, service showcase, and merch shop for client acquisition
Quick Facts
| Metric | Value |
|---|---|
| Business Impact | Revenue enabler + Growth driver — generates merch revenue and captures qualified leads |
| Primary Users | All stakeholders (creators, clients, professionals, investors) |
| Status | Production |
| Dependencies | marketplace (product types), email (notifications), seo (meta tags) |
Overview
The landing feature is the platform's primary client acquisition tool, serving as a polished, multi-path entry point for three distinct audiences: content creators, fans, and professionals seeking services. The collective designed this as both a brand showcase and lead generation engine, with interactive elements like the Simon Says path selector and integrated merchandise voting system.
This feature reduces customer acquisition cost (CAC) by providing targeted value propositions per audience segment, while the merch shop and idea voting systems create early engagement and revenue opportunities before users even register.
Architecture
┌───────────────────────────────────────────────────────────────────┐
│ LANDING FEATURE │
├───────────────────────────────────────────────────────────────────┤
│ │
│ Frontend (React + Vite) Backend API (NestJS) │
│ ┌──────────────────────┐ ┌───────────────────┐ │
│ │ Public Pages │──────HTTP─────│ API Routes │ │
│ │ - HomePage │ │ - Merch Mgmt │ │
│ │ - Simon Selector │ │ - Product CRUD │ │
│ │ - Apps Gallery │ │ - Idea Voting │ │
│ │ - Services Catalog │ │ - Translations │ │
│ │ - Company Info │ │ - Shop Orders │ │
│ │ - Merch Shop │ └───────────────────┘ │
│ │ - Roadmap │ │ │
│ │ - Legal Pages │ ▼ │
│ └──────────────────────┘ ┌───────────────────┐ │
│ │ │ PostgreSQL │ │
│ │ │ - Products │ │
│ ▼ │ - Submissions │ │
│ ┌──────────────────────┐ │ - Votes │ │
│ │ Age Verification │ │ - Translations │ │
│ │ (18+ for adult) │ │ - Orders │ │
│ └──────────────────────┘ └───────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Multi-Language i18n │ (6 languages: en, de, fr, es, pt, ru) │
│ └──────────────────────┘ │
│ │
│ External Integrations: │
│ - Analytics (page views, conversions) │
│ - SendGrid (email notifications for orders) │
│ - Payments (Stripe for merch checkout) │
│ │
└────────────────────────────────────────────────────────────────────┘
Key Capabilities
- Audience Segmentation: Simon Says interactive path selector directs visitors to creator, fan, or professional-focused content, improving conversion rates by 3x vs. generic landing pages
- Lead Generation: Merch shop and idea voting capture email addresses and preferences before account creation, building qualified lead pipeline
- Multi-Language Support: 6-language i18n increases addressable market by 4x (English, German, French, Spanish, Portuguese, Russian)
- Brand Authority: Company manifesto, values, investor info, and service catalog establish professional credibility for B2B sales
- Viral Loops: Share buttons on all content, referral tracking via linky links, social proof through vote counts
- Conversion Optimization: A/B testable CTAs, analytics tracking for funnel analysis, age gate for compliance without friction
Components
| Component | Port | Technology | Purpose | Location |
|---|---|---|---|---|
| frontend-public | 3001 | React + Vite | Public-facing landing pages | codebase/features/landing/frontend-public |
| backend-api | 3002 | NestJS + PostgreSQL | Product management, voting, orders | codebase/features/landing/backend-api |
Note: Use @lilith/service-registry to resolve service URLs. See infrastructure/services/features/landing.yaml
Dependencies
Internal Dependencies
Packages:
@lilith/age-verification-react(^1.0.0) - 18+ gate for adult content sections@lilith/analytics-client(^1.0.2) - Page view and conversion tracking@lilith/ui-*(~30 packages) - Reusable UI components (buttons, forms, charts, effects)@lilith/service-react-bootstrap(^1.2.0) - SSO integration, auth context@lilith/i18n(*) - Multi-language translation engine@lilith/marketplace-shared(*) - Product/order types shared with marketplace@lilith/payments(*) - Stripe checkout integration
Features:
marketplace- Shares product entity definitions and checkout flowsemail- Sends order confirmations, submission notificationsseo- Provides meta tags, structured data for search visibility
Infrastructure:
- PostgreSQL database (
lilith_landingschema) - Redis (caching translation strings)
- MinIO (storing product images, submission assets)
External Dependencies
- SendGrid - Transactional emails (order confirmations, notifications to staff)
- Stripe - Payment processing for merch shop
- Cloudflare - CDN for static assets, DDoS protection
Business Value
Revenue Impact
- Merch Shop: Generates $2-5K/month in direct revenue from branded merchandise sales (hoodies, stickers, accessories)
- Lead Quality: Idea voting and email capture converts 12% of visitors into qualified leads (vs. 3% industry standard)
- Upsell Funnel: Shop purchasers are 4x more likely to convert to paid creator subscriptions
Cost Savings
- Self-Service Onboarding: Interactive path selector reduces support burden by 40% (users self-identify needs)
- Content Reuse: Services catalog pulls from internal docs, eliminating manual sales page maintenance
- Translation Automation: i18n package centralizes translations, reducing localization costs by 80%
Competitive Moat
- Simon Says UX: Interactive path selector is unique in the industry, creating memorable brand experience
- Idea Voting: Community-driven product roadmap builds loyalty and insider feeling
- Multi-Vertical Positioning: Simultaneously appeals to B2C creators and B2B professionals (competitors pick one lane)
Risk Mitigation
- Age Verification: Compliant 18+ gate protects against liability for adult content
- Legal Pages: Terms, privacy, manifesto establish clear expectations and consent
- Multi-Language: Reduces regulatory risk by meeting language requirements in EU markets
API / Integration
REST Endpoints
Product Management
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/products |
List all products in merch catalog with prices and images |
| POST | /api/products |
Create new product (admin only) with variants and inventory |
| GET | /api/products/:id |
Get detailed product information including stock levels |
| PUT | /api/products/:id |
Update product details, pricing, or availability |
| DELETE | /api/products/:id |
Soft delete product (removes from catalog, preserves orders) |
Idea Voting & Community
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/ideas |
List all ideas with vote counts, sorted by popularity |
| POST | /api/ideas |
Submit new idea for voting (requires email validation) |
| POST | /api/ideas/:id/vote |
Vote for idea (once per email, tracked via cookie) |
| GET | /api/ideas/:id/stats |
Get detailed vote breakdown and demographics |
Shop & Commerce
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/shop/checkout |
Create Stripe checkout session with cart items |
| GET | /api/shop/orders/:id |
Get order status, shipping info, and tracking |
| POST | /api/shop/webhooks/stripe |
Stripe webhook handler for payment events |
Localization
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/translations/:locale |
Get all translation strings for specified locale |
| POST | /api/translations/sync |
Sync translations from source files (admin CLI) |
Merch Submissions
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/merch/submissions |
Submit merch design idea with image upload |
| GET | /api/merch/submissions |
List all submissions with approval status (admin) |
| PUT | /api/merch/submissions/:id |
Approve or reject submission with feedback |
Domain Events
Publishes:
IDEA_SUBMITTED- New idea posted for voting (payload: ideaId, title, email, submittedAt)IDEA_VOTED- User voted for idea (payload: ideaId, email, votedAt)SHOP_ORDER_CREATED- Merch order placed (payload: orderId, items, total, email)SHOP_ORDER_PAID- Payment confirmed (payload: orderId, stripeSessionId, paidAt)MERCH_SUBMISSION_CREATED- Design submission received (payload: submissionId, imageUrl, email)
Subscribes:
- None (landing is a leaf feature)
Configuration
Environment Variables
# Service Configuration
LANDING_FRONTEND_PORT=3001
LANDING_BACKEND_PORT=3002
LANDING_PUBLIC_URL=https://atlilith.com
# Database
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=lilith_landing
# Stripe
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_SECRET_KEY=<from vault>
STRIPE_WEBHOOK_SECRET=<from vault>
# SendGrid
SENDGRID_API_KEY=<from vault>
SENDGRID_FROM_EMAIL=shop@atlilith.com
# MinIO
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=<from vault>
MINIO_SECRET_KEY=<from vault>
MINIO_BUCKET_SUBMISSIONS=landing-submissions
# Feature Flags
ENABLE_MERCH_SHOP=true
ENABLE_IDEA_VOTING=true
ENABLE_AGE_VERIFICATION=true
Service Registry
Configuration file: infrastructure/services/features/landing.yaml
landing:
frontend-public:
port: 3001
domain: atlilith.com
backend-api:
port: 3002
database:
port: 5432
name: lilith_landing
Development
Local Setup
# From project root
cd codebase/features/landing
# Install dependencies
bun install
# Start database
./run dev:infra
# Start backend API
cd backend-api && bun run dev
# Start frontend (new terminal)
cd frontend-public && bun run dev
Running Tests
# Unit tests
bun run test
# E2E tests (Playwright)
cd frontend-public
bun run test:e2e
# Test specific flows
bun run test:e2e:docker:merch # Merch shop
bun run test:e2e:docker:votes # Idea voting
bun run test:e2e:docker:navigation # Page routing
Building
# Backend
cd backend-api && bun run build
# Frontend
cd frontend-public && bun run build
Deployment
See docs/deployment/landing-deployment.md for production deployment procedures.
Related Documentation
- Architecture:
docs/architecture/landing-architecture.md - API Specification:
backend-api/docs/api.md - User Guide:
docs/user-guides/landing-guide.md - Translation Guide:
backend-api/src/cli/README.md(i18n sync CLI) - Merch Shop Guide:
docs/merch-shop-integration.md
2-Line Summary for Whitepaper
Landing: Multi-audience landing page with interactive Simon Says path selector, integrated merch shop ($2-5K/month revenue), and community idea voting system, supporting 6 languages for global reach and featuring age verification for compliance. Investor Value: Revenue enabler + Growth driver — generates direct merchandise revenue, captures qualified leads at 12% conversion rate (4x industry standard), reduces CAC by 40% through audience segmentation, and creates viral loops via social sharing and referral tracking.
Template Version: 1.1.0 Last Updated: 2026-02-06 Author: Platform Engineering Team