Skip to main content

Sprint 0: Infrastructure Foundation - Objectives Report

Project: The Villa Life (TVL) Platform Sprint: Sprint 0 - Infrastructure Foundation Duration: Weeks 0-2 (2 week sprint) Phase: Pre-MVP.0 (Foundation) Document Type: Strategic Objectives & Planning Date Created: October 28, 2025

Executive Summary​

Sprint 0 will establish the technical foundation required for MVP.0 development. Unlike feature sprints, Sprint 0 focuses entirely on infrastructure, tooling, and developer experience. Success means enabling a team to build MVP.0 efficiently with production-grade patterns from day one.

Primary Goal: Create a production-ready development environment that enables rapid, high-quality delivery of MVP.0 features across 5 domains (Identity, Authorization, Supply, Channels, Analytics).

Strategic Context​

Why Sprint 0?​

The TVL Platform is a multi-tenant SaaS application built with domain-driven design principles. Before implementing business logic, we need:

  1. Reliable Infrastructure - Local development mirrors production
  2. Type Safety - TypeScript strict mode + ORM prevents runtime errors
  3. Automated Quality - CI/CD catches issues before merge
  4. Developer Velocity - Tools reduce friction (Linear CLI, secrets management)
  5. Documentation Infrastructure - Knowledge sharing from day one

Without Sprint 0: Teams waste 30-40% of sprint time on tooling issues, environment inconsistencies, and manual processes.

With Sprint 0: Developers focus on domain logic, tests pass reliably, deploys are predictable.

Sprint 0 Objectives​

Objective 1: Establish Development Environment​

Priority: CRITICAL Owner: Platform/DevOps Estimated Effort: 4-6 hours

Goal: Every developer can clone the repo and be productive within 30 minutes.

Key Results:

  • Docker Compose with PostgreSQL 15 + pgAdmin configured
  • Database initialization automatic (extensions, users, schemas)
  • Health checks ensure services ready before acceptance
  • .env.example template with all required variables documented

Success Metric: New developer runs 3 commands (clone, docker up, pnpm install) and has working environment.

Deliverables:

  • /workspace/docker-compose.yml
  • /workspace/packages/database/scripts/init-db.sh
  • /workspace/.env.example

Enables:

  • Consistent local development across Windows/Mac/Linux
  • Rapid onboarding of new team members
  • Parity between local and cloud environments

Linear Ticket: ARC-27

Objective 2: Implement Type-Safe Database Layer​

Priority: CRITICAL Owner: Backend Engineering Estimated Effort: 8-12 hours

Goal: Database changes are type-safe, versioned, and testable.

Key Results:

  • Drizzle ORM installed with PostgreSQL adapter
  • TypeScript schemas for 22 tables across 5 domains
  • SQL migrations in chronological files (single source of truth)
  • Test infrastructure with Vitest for schema validation
  • Database client with connection pooling
  • Drizzle Kit commands (push, studio, generate) operational

Success Metric: Schema changes generate TypeScript types automatically. Tests fail if DB and code are out of sync.

Deliverables:

  • /workspace/packages/database/src/schema/ (5 domain schemas)
  • /workspace/packages/database/migrations/mvp.0/001_initial_schema.sql
  • /workspace/packages/database/src/client.ts
  • /workspace/packages/database/drizzle.config.ts

Enables:

  • Compile-time safety (no more "column not found" runtime errors)
  • Reliable migrations with rollback capability
  • Fast feedback loop for database changes

Linear Ticket: ARC-28

Objective 3: Configure Secrets Management​

Priority: CRITICAL Owner: Platform/DevOps Estimated Effort: 3-4 hours

Goal: No secrets in git. Environment variables managed centrally and synced automatically.

Key Results:

  • Doppler CLI integration with automated setup script
  • Environment mapping (dev/stg/prd → development/staging/production)
  • NODE_ENV vs APP_ENV strategy documented (ADR-0055)
  • Secrets rotation workflow documented
  • .env.local auto-generated from Doppler (never committed)

Success Metric: Rotating a secret takes 10 minutes (update Doppler, team syncs) instead of 2 hours (update 5 .env files, notify team, debug issues).

Deliverables:

  • /workspace/scripts/setup-doppler-env.sh
  • /workspace/docs/reference/decisions/adr-0055-environment-variable-strategy.md
  • /workspace/docs/reference/decisions/adr-0008-doppler-secrets-management.md

Enables:

  • SOC 2 compliance (audit logs, access control)
  • Safe secret rotation without coordination overhead
  • Prevention of leaked credentials in git history

Linear Ticket: ARC-29

Objective 4: Build Backend API Foundation​

Priority: CRITICAL Owner: Backend Engineering Estimated Effort: 8-12 hours

Goal: RESTful API with OpenAPI docs, health checks, and ORM integration.

Key Results:

  • Fastify 4.x installed with TypeScript support
  • Health check endpoint (GET /health) operational
  • @fastify/swagger generating OpenAPI 3.0 documentation
  • CORS and security headers configured
  • Environment variable validation (@fastify/env)
  • Database client integration (Drizzle ORM)
  • API route structure for 5 domains

Success Metric: curl http://localhost:3001/health returns {"status":"ok"} and Swagger UI accessible at /docs.

Deliverables:

  • /workspace/apps/api-gateway/src/server.ts
  • /workspace/apps/api-gateway/src/routes.ts
  • /workspace/apps/api-gateway/src/plugins/
  • /workspace/apps/api-gateway/tests/

Enables:

  • Frontend can fetch data via REST APIs
  • API contracts documented and auto-updated
  • Foundation for all MVP.0 domain endpoints

Linear Ticket: ARC-30

Objective 5: Setup Frontend Foundation​

Priority: CRITICAL Owner: Frontend Engineering Estimated Effort: 6-8 hours

Goal: Production-ready React application with styling, routing, and type safety.

Key Results:

  • Next.js 14 with App Router and TypeScript strict mode
  • Tailwind CSS + Shadcn UI components
  • Base layouts and home page scaffolded
  • ESLint + Prettier configured
  • Build succeeds with no errors
  • Development server with hot reload

Success Metric: pnpm dev:web starts dev server. pnpm build:web produces optimized production bundle.

Deliverables:

  • /workspace/apps/web/app/layout.tsx
  • /workspace/apps/web/app/page.tsx
  • /workspace/apps/web/tailwind.config.ts
  • /workspace/apps/web/components/ (Shadcn UI setup)

Enables:

  • Rapid UI development with pre-built components
  • Type-safe API client integration (TanStack Query)
  • Production-grade performance (Next.js optimizations)

Linear Ticket: ARC-31

Objective 6: Implement CI/CD Automation​

Priority: HIGH Owner: Platform/DevOps Estimated Effort: 4-6 hours

Goal: Every PR is automatically tested. Merges to main deploy to staging.

Key Results:

  • Main CI workflow (type-check, lint, test)
  • Database tests with PostgreSQL service
  • Build validation for Next.js and API
  • Documentation deployment workflow (Cloudflare Pages)
  • Nx affected detection (only test changed packages)
  • pnpm caching configured

Success Metric: PR cannot merge if CI fails. All tests run automatically on every push.

Deliverables:

  • /workspace/.github/workflows/ci.yml
  • /workspace/.github/workflows/database-tests.yml
  • /workspace/.github/workflows/deploy-docs.yml

Enables:

  • Prevention of broken code reaching main branch
  • Fast feedback for developers (failures in 5 minutes)
  • Confidence in deployments (tested code only)

Linear Ticket: ARC-32

Objective 7: Configure Monorepo Build System​

Priority: HIGH Owner: Platform Engineering Estimated Effort: 4-6 hours

Goal: Fast, cached builds with clear package boundaries.

Key Results:

  • pnpm workspaces configured (@tvl/* namespace)
  • TypeScript base configuration with path aliases
  • Root scripts for workspace commands
  • Nx build system installed and configured
  • Build caching configured (local + CI)
  • Affected detection (only build changed packages)
  • Shared packages created (@tvl/types, @tvl/utils, @tvl/constants)

Success Metric: Changing one package only rebuilds that package and dependents (not entire monorepo).

Deliverables:

  • /workspace/pnpm-workspace.yaml
  • /workspace/tsconfig.base.json
  • /workspace/nx.json
  • /workspace/packages/shared/{types,utils,constants}/

Enables:

  • Fast CI/CD (build only what changed)
  • Clear dependency graph prevents circular imports
  • Shared code reduces duplication

Linear Ticket: ARC-33

Objective 8: Deploy Documentation Infrastructure​

Priority: MEDIUM Owner: Platform Engineering Estimated Effort: 4-5 hours

Goal: Centralized, searchable documentation for team and stakeholders.

Key Results:

  • Docusaurus 3.9 with TypeScript installed
  • OpenAPI plugin generating API endpoint docs
  • Integration with /docs/ directory (single source of truth)
  • GitHub Actions workflow for auto-deployment
  • Cloudflare Pages configuration complete
  • Local build tested and passing
  • Cloudflare Pages project created and deployed

Success Metric: Developer commits markdown to /docs/. Within 5 minutes, changes live at https://docs.thevillalife.app.

Deliverables:

  • /workspace/apps/docs-site/ (complete Docusaurus installation)
  • /workspace/.github/workflows/deploy-docs.yml
  • /workspace/apps/docs-site/wrangler.toml
  • /workspace/apps/docs-site/DEPLOYMENT.md

Enables:

  • Onboarding documentation (setup guides, architecture)
  • API documentation auto-generated from OpenAPI specs
  • Sprint reports and decisions accessible to all stakeholders

Linear Tickets: ARC-35, ARC-38

Objective 9: Integrate Developer Tooling​

Priority: MEDIUM Owner: Any Engineer Estimated Effort: 3-4 hours

Goal: Reduce manual work with CLI tools and workflow automation.

Key Results:

  • Linear CLI with create/update/list/search/teams commands
  • /checkin-with-ticket slash command (auto-links commits to tickets)
  • Automatic ticket detection from branch names (feat/ARC-10-fix)
  • Cursor IDE integration rules
  • Workflow documented in CLAUDE.md

Success Metric: Developer types /checkin-with-ticket, gets prompted for changes, commit created with ticket link automatically.

Deliverables:

  • /workspace/scripts/linear-cli.ts
  • /workspace/.claude/commands/checkin-with-ticket.md
  • /workspace/.cursor/rules/10-checkin-with-ticket.mdc
  • /workspace/CLAUDE.md (Git Commit Guidelines section)

Enables:

  • Traceability (every commit linked to Linear ticket)
  • Faster commits (no manual ticket reference typing)
  • Better sprint reporting (commits grouped by ticket)

Linear Ticket: ARC-34

Objective 10: Document Architecture Decisions​

Priority: MEDIUM Owner: Tech Lead/Architect Estimated Effort: 3-4 hours

Goal: All technical decisions documented and searchable.

Key Results:

  • Audit existing ADRs for completeness
  • Verify all Sprint 0 tools have ADRs
  • Create missing ADRs (estimated 2-3)
  • Update ADR index in /docs/reference/decisions/README.md
  • Ensure consistency with CLAUDE.md technology stack

Success Metric: New engineer asks "Why did we choose Fastify?" Finds ADR-0022 in 30 seconds.

Deliverables:

  • /workspace/docs/reference/decisions/adr-00XX-*.md (new ADRs)
  • /workspace/docs/reference/decisions/README.md (updated index)

Enables:

  • Context for future engineers (avoid "why did they do this?" confusion)
  • Prevent relitigating decisions already made
  • Onboarding documentation for new team members

Linear Ticket: ARC-36

Success Criteria​

Primary Success Criteria (Must Have)​

Sprint 0 will be successful when:

  1. Environment Setup Takes < 30 Minutes

    • New developer: clone → docker up → pnpm install → working
    • No manual database setup required
    • No secret sharing via Slack needed

  2. Database Changes Are Type-Safe

    • Drizzle schemas generate TypeScript types
    • Migrations run reliably (no manual SQL)
    • Tests validate schema correctness

  3. API Foundation is Operational

    • Health check endpoint responds
    • OpenAPI docs accessible
    • Database queries work via ORM

  4. Frontend Builds Successfully

    • Next.js dev server runs
    • Production build completes
    • No TypeScript errors

  5. CI/CD Prevents Broken Code

    • PRs require passing tests
    • Type check + lint + tests run automatically
    • Builds validated before merge

Secondary Success Criteria (Should Have)​

  1. Documentation Infrastructure Ready

    • Docusaurus builds locally
    • API docs auto-generated
    • Deployment workflow configured
    • Public access via Cloudflare Pages

  2. Monorepo Build System Complete

    • Nx installed and configured
    • Build caching enabled
    • Shared packages created

  3. Developer Tooling Operational

    • Linear CLI working
    • Commit-ticket linking automated

Tertiary Success Criteria (Nice to Have)​

  1. Documentation Publicly Accessible

    • Cloudflare Pages deployed
    • Custom domain configured (optional)
    • Team can access docs from anywhere

  2. ADRs Complete and Audited

    • All tools have documented decisions
    • Index up-to-date
    • Easy to search

Sprint Timeline​

Week 0-1 (Days 1-5)​

Day 1-2: Critical Infrastructure

  • Objective 1: Development Environment (4-6 hours)
  • Objective 3: Secrets Management (3-4 hours)
  • Objective 2: Database Layer (start, 4-6 hours)

Day 3-4: Application Foundations

  • Objective 2: Database Layer (complete, 4-6 hours)
  • Objective 4: Backend API (8-12 hours)
  • Objective 5: Frontend Foundation (6-8 hours)

Day 5: Automation & Tooling

  • Objective 6: CI/CD (start, 2-3 hours)
  • Objective 7: Monorepo (start, 2-3 hours)

Week 1-2 (Days 6-10)​

Day 6-7: Complete Build System

  • Objective 6: CI/CD (complete, 2-3 hours)
  • Objective 7: Monorepo (complete, 2-3 hours)
  • Objective 8: Documentation (4-5 hours)

Day 8-9: Developer Experience

  • Objective 9: Developer Tooling (3-4 hours)
  • Objective 10: ADR Audit (3-4 hours)

Day 10: Final Testing & Validation

  • Integration testing across all objectives
  • Documentation review
  • Sprint retrospective
  • Transition planning to MVP.0

Alignment with MVP.0​

MVP.0 Dependency Map​

Sprint 0 is the prerequisite for MVP.0 implementation. Without Sprint 0, MVP.0 work will be blocked or significantly slowed:

MVP.0 DomainSprint 0 DependencyImpact if Missing
Identity & TenancyBackend API (Obj. 4) + Database (Obj. 2)BLOCKED - No way to create orgs/users
Authorization & AccessBackend API (Obj. 4) + Database (Obj. 2)BLOCKED - RBAC APIs unavailable
Supply ManagementBackend API (Obj. 4) + Frontend (Obj. 5) + Database (Obj. 2)BLOCKED - No CRUD endpoints or UI
Channels & DistributionBackend API (Obj. 4) + Database (Obj. 2)BLOCKED - Sync APIs don't exist
Analytics & AuditBackend API (Obj. 4) + Database (Obj. 2)BLOCKED - Logging endpoints unavailable

Critical Path: Objectives 1-5 (all CRITICAL priority) must complete before any MVP.0 domain work can begin.

Business Value Timeline​

Sprint 0 (Weeks 0-2) → MVP.0 (Weeks 1-10) → Production Launch
    ↓                       ↓                      ↓
Infrastructure         Feature Development     Customer Value
No revenue yet         No revenue yet          Revenue generation begins

Sprint 0 Investment: 2 weeks (45-60 hours total)
MVP.0 Development: 10 weeks
Business Value: Week 11+ (first paying customer)

Why This Matters:

  • Sprint 0 costs time but prevents technical debt
  • Poor infrastructure = 30-40% slower MVP.0 development
  • Investing 2 weeks saves 3-4 weeks during MVP.0
  • Production-grade patterns prevent costly rewrites

Resource Requirements​

Time Investment​

ObjectivePriorityEstimated HoursOwner
1. Development EnvironmentCRITICAL4-6 hoursPlatform/DevOps
2. Database LayerCRITICAL8-12 hoursBackend Engineer
3. Secrets ManagementCRITICAL3-4 hoursPlatform/DevOps
4. Backend APICRITICAL8-12 hoursBackend Engineer
5. Frontend FoundationCRITICAL6-8 hoursFrontend Engineer
6. CI/CD AutomationHIGH4-6 hoursDevOps Engineer
7. Monorepo Build SystemHIGH4-6 hoursPlatform Engineer
8. DocumentationMEDIUM4-5 hoursPlatform Engineer
9. Developer ToolingMEDIUM3-4 hoursAny Engineer
10. ADR DocumentationMEDIUM3-4 hoursTech Lead
Total Estimated47-67 hours

Team Allocation​

RolePrimary ObjectivesEstimated TimeParallel Work Possible
Backend EngineerObj. 2, 416-24 hoursYes (with Frontend)
Frontend EngineerObj. 56-8 hoursYes (with Backend)
DevOps EngineerObj. 1, 3, 611-16 hoursYes (with Platform)
Platform EngineerObj. 7, 88-11 hoursYes (with DevOps)
Any EngineerObj. 93-4 hoursFlexible timing
Tech LeadObj. 103-4 hoursFlexible timing

Optimal Team Size: 3-4 engineers working in parallel

Minimum Team Size: 2 engineers (Backend + DevOps/Platform hybrid)

External Dependencies​

  • Cloudflare Account Access: Required for Objective 8 (25-55 min setup)
  • GitHub Admin Access: Required for CI/CD secrets configuration
  • Linear Account: Required for Objective 9 (API key)
  • Doppler Account: Required for Objective 3 (free tier sufficient)

Risk Assessment​

High-Risk Areas​

🚨 Risk 1: Backend API Complexity​

Probability: Medium Impact: High (blocks MVP.0 if delayed) Mitigation:

  • Start Objective 4 early in sprint (Day 3-4)
  • Assign experienced Fastify developer
  • Use ADR-0022 as implementation guide
  • Daily progress check-ins

Contingency: If delayed, implement minimal health check + 1 domain endpoint to unblock MVP.0 start.

⚠️ Risk 2: Database Schema Changes​

Probability: Medium Impact: Medium (rework if schema incorrect) Mitigation:

  • Review domain specifications before schema creation
  • Use Drizzle schema validation tests
  • Peer review all migration SQL
  • Test migrations in clean database

Contingency: Maintain migration rollback capability. Version all schemas.

⚠️ Risk 3: CI/CD Setup Complexity​

Probability: Low Impact: Medium (manual testing if not ready) Mitigation:

  • Use existing GitHub Actions templates
  • Start with simple workflow, expand incrementally
  • Test locally with act tool before pushing

Contingency: Manual testing acceptable for Sprint 0. Complete CI/CD in parallel with early MVP.0 work.

Medium-Risk Areas​

ℹ️ Risk 4: Nx Learning Curve​

Probability: Medium Impact: Low (monorepo works without Nx, just slower) Mitigation:

  • Follow official Nx documentation
  • Start with basic configuration
  • Add caching incrementally

Contingency: Use pnpm workspaces without Nx initially. Add Nx optimization later.

ℹ️ Risk 5: Documentation Deployment Issues​

Probability: Low Impact: Low (local docs still usable) Mitigation:

  • Test Docusaurus build locally first
  • Use Cloudflare Pages template
  • Allocate buffer time for troubleshooting

Contingency: Use local Docusaurus builds (pnpm serve) until deployment resolved.

Key Deliverables Summary​

Infrastructure Components​

  1. Docker Compose environment (PostgreSQL + pgAdmin)
  2. Database layer with Drizzle ORM (22 tables, 5 domains)
  3. Doppler secrets management integration
  4. Fastify backend API with OpenAPI docs
  5. Next.js frontend with Tailwind + Shadcn UI

Automation & Tooling​

  1. GitHub Actions CI/CD workflows
  2. Nx monorepo build system
  3. Docusaurus documentation site
  4. Linear CLI with commit automation
  5. Architecture Decision Records (ADRs)

Documentation​

  • Environment setup guide (README.md)
  • Database migration documentation
  • Secrets management guide
  • API documentation (auto-generated)
  • Architecture decisions (ADRs)
  • Sprint 0 completion report

Measurement & Tracking​

Daily Standups​

Focus Questions:

  1. Which objective(s) are you working on today?
  2. Any blockers preventing completion?
  3. Is your objective on track for sprint timeline?

Progress Tracking​

Metrics to Track:

  • Objectives completed (target: 10/10)
  • Hours invested vs. estimated
  • Blockers encountered and resolved
  • Quality issues found during testing

Tools:

  • Linear for ticket tracking (ARC-27 through ARC-38)
  • GitHub for commit history and PRs
  • Sprint board for visual progress

Success Validation​

End-of-Sprint Checklist:

  • All 5 critical objectives complete
  • All 2 high-priority objectives complete
  • Environment setup tested with new developer
  • All tests passing in CI
  • Documentation reviewed and published
  • Retrospective completed
  • MVP.0 kickoff meeting scheduled

Transition to MVP.0​

Sprint 0 Complete When:​

Critical Requirements:

  • All 5 critical objectives complete (Obj. 1-5)
  • Backend API health check responds
  • Frontend builds and runs locally
  • Database migrations tested
  • CI/CD running on PRs

High Priority Requirements:

  • CI/CD workflows operational (Obj. 6)
  • Nx build system configured (Obj. 7)

Optional (Can Complete During MVP.0):

  • Documentation publicly deployed (Obj. 8)
  • Developer tooling fully integrated (Obj. 9)
  • ADR audit complete (Obj. 10)

MVP.0 Kickoff Plan​

Week 3 (Post-Sprint 0):

  • Sprint 0 retrospective and lessons learned
  • Environment validation with full team
  • MVP.0 planning session
  • First MVP.0 epic kickoff: Identity & Tenancy (ARC-13)

Success Criteria for Transition:

  • New developer onboarded in < 30 minutes
  • Backend API responds to health check
  • Frontend dev server running
  • CI/CD blocks broken PRs
  • Team confident in infrastructure

Appendix​

  • MVP.0 Specification: /docs/specifications/versions/mvp.0_specification.md
  • Repository Structure: .claude/planning/repository-structure-strategy.md
  • ADR Index: /docs/reference/decisions/README.md
  • Technology Stack: CLAUDE.md (complete stack documentation)

Linear Epic​

Sprint 0: Infrastructure Foundation

  • Epic tracking all 10 objectives
  • Tickets: ARC-27 through ARC-38
  • Owner: Platform Team
  • Timeline: Weeks 0-2

Key Architecture Decisions​

Database:

  • ADR-0002: PostgreSQL as primary database
  • ADR-0012: Drizzle ORM for type-safe queries

Backend:

  • ADR-0022: Fastify for backend API framework
  • ADR-0024: OpenAPI 3.0 for API documentation

Frontend:

  • ADR-0015: React for frontend UI
  • ADR-0016: Next.js for server-side rendering

Infrastructure:

  • ADR-0008: Doppler for secrets management
  • ADR-0011: Nx for monorepo build system
  • ADR-0052: Docusaurus + Cloudflare Pages for docs
  • ADR-0055: NODE_ENV vs APP_ENV strategy

Full Index: /docs/reference/decisions/README.md

Report Metadata​

Document Type: Sprint Objectives & Planning Report Date: October 28, 2025 Sprint: Sprint 0 (Infrastructure Foundation) Project Phase: Pre-MVP.0 Author: TVL Platform Team Distribution: Development Team, Product, Leadership Classification: Internal Use Next Report: Sprint 0 Status Update (Mid-sprint check-in)

This objectives report defines the goals, tasks, and success criteria for Sprint 0. It serves as the planning document for infrastructure foundation work before MVP.0 development begins.