Project Wiki
Back to app
Browse documents

Phase 0 — Foundation & Setup

Status: Shipped ✅ · Owner: Engineering Lead · Duration: 1 week · Gate: G0

1. Overview

Phase 0 stands up the engineering foundation that every subsequent phase depends on: source-control layout, CI/CD, environment topology, secrets handling, base design system, and the per-phase documentation conventions. No product features are built here. The output is a clean, working scaffold that an engineer can clone, run, and start coding against on day one of Phase 2.

2. Objectives

  • O0.1 — Monorepo committed with Next.js 15 app skeleton building cleanly on local + CI.
  • O0.2 — Three environments live (dev, staging, prod) with isolated MongoDB instances and secret stores.
  • O0.3 — CI pipeline running lint, type-check, unit-test, build, container, and security scan on every PR.
  • O0.4 — Design system seed in Storybook with theme tokens, base components, and dark/light themes proven.
  • O0.5 — Repository conventions documented (branching, commit, PR, ADR, changelog).

3. Scope

3.1 In-scope

  • Source repo creation (GitHub) with branch protection, code owners, required reviews.
  • Next.js 15 app skeleton (TypeScript strict, App Router, /app, /components, /lib, /server, /types).
  • MongoDB connection helper with MONGODB_URI from .env.local (dev) and platform secret store (stage/prod).
  • .env.example documenting every required variable.
  • Tailwind CSS + shadcn/ui base install, theme tokens (CSS variables) for light/dark + brand palette.
  • Storybook 8 with stories for Button, Input, Card, Modal, Toast, Table.
  • ESLint + Prettier + Husky + lint-staged pre-commit.
  • Vitest + Playwright configured with a sample passing test of each kind.
  • GitHub Actions workflows: pr.yml (lint+test+typecheck+build), main.yml (deploy staging), release.yml (deploy prod on tag).
  • Container build (Dockerfile, multi-stage) + image scan (Trivy).
  • Secret management strategy documented (1Password / Doppler / Vault / cloud-native KMS — choice recorded in ADR-001).
  • Per-phase doc folder (/docs/engineering/Phase_N.md) and ADR folder (/docs/adr/).

3.2 Out-of-scope

  • Authentication implementation (Phase 2).
  • Database schemas beyond a placeholder health-check ping (Phase 1 designs, Phase 2 implements).
  • Any product UI screens.
  • Production hosting decisions beyond "container ready."

4. Dependencies

  • None (this is the first phase). Cloud accounts (MongoDB Atlas, GitHub, container registry) must exist before kickoff.

5. Architecture & Design

5.1 Repository layout (target)

/
├── .github/
│   └── workflows/             # pr.yml, main.yml, release.yml
├── apps/
│   └── web/                   # Next.js 15 app
│       ├── app/
│       ├── components/
│       ├── lib/
│       ├── server/            # API route handlers, server actions
│       ├── styles/
│       └── public/
├── packages/                  # Shared (Phase 1+ may add @gp/schemas, @gp/sdk)
├── storybook/
├── docs/
│   ├── engineering/           # Phase_N.md files
│   ├── adr/                   # ADR-NNN-title.md files
│   └── runbooks/
├── docker/
│   └── Dockerfile
├── .env.example
├── .nvmrc                     # Node LTS
├── package.json
├── tsconfig.json
├── tailwind.config.ts
└── README.md

5.2 Environment topology

EnvPurposeURLDBAuthDeploy trigger
LocalDev laptopslocalhost:3000Local Mongo / Atlas dev clusterMockn/a
StagingIntegrationstg.atlas.exampleAtlas (small)RealPush to main
ProdCustomerapp.atlas.exampleAtlas (clustered)RealTag v*.*.*

5.3 .env.example (foundation set)

# --- Database ---
MONGODB_URI=mongodb://localhost:27017/atlas_dev
MONGODB_DB_NAME=atlas_dev

# --- Application ---
NEXT_PUBLIC_APP_NAME=Atlas
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

# --- Auth (Phase 2 fills) ---
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000

# --- AI providers (Phase 6 fills) ---
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
AI_PROVIDER=anthropic
AI_MODEL=claude-sonnet-4-6

# --- Object store (Phase 4 fills) ---
S3_ENDPOINT=
S3_BUCKET=
S3_ACCESS_KEY=
S3_SECRET_KEY=

# --- Telemetry (Phase 2 fills) ---
OTEL_EXPORTER_OTLP_ENDPOINT=

# --- Feature flags ---
FEATURE_AI_SECOND_BRAIN=false
FEATURE_WORKFLOW_STUDIO=false

5.4 Design system seed

  • Tokens are CSS variables on :root (and .dark). Token names map to Tailwind via tailwind.config.ts.
  • Tokens cover: color (primary, secondary, accent, neutral, semantic), spacing (4-pt grid), typography (Inter or Geist), radius, shadow, motion.
  • Base components shipped: Button, Input, Textarea, Select, Checkbox, Switch, Card, Modal/Sheet, Toast, Tooltip, Table, Tabs, Badge.
  • Storybook stories for every base component with light/dark previews.

6. Implementation Tasks

Epic 0.A — Repository & tooling

  • 0.A.1 Create GitHub repo with branch protection on main (require 1 review, signed commits optional).
  • 0.A.2 Add CODEOWNERS, PR template, issue templates.
  • 0.A.3 Add .nvmrc, package.json, tsconfig.json (strict), .editorconfig.
  • 0.A.4 Install ESLint (next/core-web-vitals + ts), Prettier, lint-staged, Husky pre-commit.
  • 0.A.5 Commit conventional-commit lint (commitlint).

Epic 0.B — Next.js skeleton

  • 0.B.1 npx create-next-app@latest with TS, App Router, Tailwind, ESLint.
  • 0.B.2 Add base directory structure per §5.1.
  • 0.B.3 Implement /api/health (returns 200 with version + db ping).
  • 0.B.4 Implement /lib/db.ts (MongoDB client singleton, reads MONGODB_URI).
  • 0.B.5 Configure Tailwind with theme tokens, dark mode via class.

Epic 0.C — Design system seed

  • 0.C.1 Install shadcn/ui CLI, generate base components (Button, Input, Card, Modal, Toast, Tooltip, Tabs, Badge, Switch).
  • 0.C.2 Add Storybook 8 with Vite builder.
  • 0.C.3 Stories for each base component + theme switcher.
  • 0.C.4 Color token reference page in Storybook.

Epic 0.D — CI / CD

  • 0.D.1 pr.yml: install, lint, type-check, unit-test, build, container build, Trivy scan.
  • 0.D.2 main.yml: deploy to staging on merge to main.
  • 0.D.3 release.yml: deploy to prod on v*.*.* tag (manual approval required).
  • 0.D.4 Dependabot configured (weekly), CodeQL enabled.

Epic 0.E — Environments & secrets

  • 0.E.1 MongoDB Atlas projects created (dev shared, staging dedicated, prod dedicated). Connection strings written to platform secret store.
  • 0.E.2 Document secret-management decision in ADR-001 (Doppler / 1Password / Vault / cloud KMS).
  • 0.E.3 Vercel / Render / Fly / self-host decision in ADR-002.

Epic 0.F — Documentation seed

  • 0.F.1 Commit 00_README.md (this folder) and Phase docs.
  • 0.F.2 Seed ADR folder with ADR-000 template and ADR-001 + ADR-002.
  • 0.F.3 Seed runbook folder with incident_response.md skeleton.
  • 0.F.4 README at repo root with quick-start (clone, install, env, run, test).

7. Acceptance Criteria

  • AC0.1 — A new engineer can clone the repo, run cp .env.example .env.local, fill MONGODB_URI, run pnpm install && pnpm dev, and see the app at localhost:3000 with /api/health returning a green DB ping in under 15 minutes.
  • AC0.2 — A PR opened against main triggers all five CI jobs (lint, typecheck, test, build, scan) and they pass on a hello-world change.
  • AC0.3 — Storybook builds and serves all base components in both themes.
  • AC0.4 — Merging to main deploys to staging automatically.
  • AC0.5 — Two ADRs (ADR-001 secret-management, ADR-002 hosting) are committed and accepted.

8. Test Requirements

  • Unit test: at least one for /lib/db.ts connection helper (mocked client).
  • Component test: one Vitest+RTL test for a base component (Button click).
  • Playwright smoke: navigate to / and assert health endpoint is reachable.
  • Coverage threshold of ≥80% enforced (will fail meaningfully only as code grows; set the threshold now).

9. Documentation Requirements

  • Root README.md quick-start (above).
  • docs/engineering/00_README.md (index of phase docs).
  • docs/engineering/Phase_0.md (this file, kept in sync).
  • docs/adr/ADR-001-secret-management.md.
  • docs/adr/ADR-002-hosting-platform.md.
  • docs/runbooks/incident_response.md (skeleton).

10. Sign-off Criteria (Gate G0)

  • All Acceptance Criteria met.
  • Engineering Lead and Product Owner sign _gates/Gate_G0_signoff.md.
  • Repo handed off ready for Phase 1 work to commence.

11. Risks & Mitigations

RiskLIMitigation
MongoDB Atlas account provisioning delays23Open Atlas accounts in week 0; have local Mongo container fallback.
Hosting platform choice debated past G022Defer non-blocking sub-decisions to ADR addenda; lock the principal choice.
Designer not ready with brand tokens32Use neutral palette + brand --primary placeholder; refresh tokens in Phase 5.