SYSTEM/docs/stories/1.1.project-initialization-main-ledger.md

Story 1.1: Project Initialization & The Main Ledger

Status

Done

Story

As a System Operator, I want to set up the initial project structure, including the application framework, database, and deployment configuration, so that there is a stable and ready foundation for all future development.

Acceptance Criteria

1. A Nuxt 4 project is successfully created and configured in a monorepo.
2. A docker-compose.yml file is created to run the Nuxt application and a PostgreSQL database service.
3. The Nuxt application can successfully connect to the PostgreSQL database on startup.
4. The initial database schema, including tables for "The Main Ledger" and "The Registry", is created via a migration script.
5. SCSS and Tailwind CSS are installed and correctly configured within the Nuxt project.

Tasks / Subtasks

• Baseline and verify Nuxt 4 setup (AC: 1)

  • Confirm Node.js >= 20 and package manager availability.
  • Verify nuxt.config.ts modules include @primevue/nuxt-module and @prisma/nuxt; ensure SSR defaults are intact. [Source: architecture/tech-stack.md#3. Tech Stack (Revised)]
  • Run dev server and confirm app boots without errors.

• Add containerized local environment with Docker Compose (AC: 2)

  • Create docker-compose.yml at repository root to run services:
    • web: Nuxt app (dev) with proper ports and env mounts.
    • db: PostgreSQL with named volume and healthcheck.
  • Provide .env with DATABASE_URL for Postgres (connection string for Prisma). [Source: architecture/unified-project-structure.md#6. Unified Project Structure]

• Configure Prisma and database connectivity (AC: 3)

  • Ensure @prisma/nuxt module is enabled in nuxt.config.ts.
  • Select a single Prisma client usage approach and unify:
    • Prefer @prisma/nuxt composable (e.g., const prisma = usePrismaClient()), or alternatively retain lib/prisma.ts singleton — but do NOT use both. Better lib/prisma.ts.
    • Update any imports/usages accordingly to prevent multiple client instances.
  • Set DATABASE_URL and run prisma generate to produce client.
  • Add a simple health endpoint server/api/health.get.ts that pings Prisma (e.g., await prisma.$queryRaw or await prisma.$executeRaw) and returns { db: 'ok' } on success.
  • Boot app; verify Prisma client can connect (check health endpoint or log on server start). [Source: architecture/tech-stack.md#3. Tech Stack (Revised)]

• Define initial database schema and migrations (AC: 4)

  • Design models for "Main Ledger" and "Registry" aligned with PRD.
  • Update prisma/schema.prisma accordingly.
  • Run prisma migrate dev --name init to create and apply the first migration.
  • Add a minimal seed script (optional) to validate queries against both tables. [Source: architecture/unified-project-structure.md#6. Unified Project Structure]

• Establish SCSS structure and integrate Tailwind (AC: 5)

  • Create SCSS directories and partials under app/assets/scss/ per project structure guidance; add css: ['~/assets/scss/main.scss'] in nuxt.config.ts. [Source: architecture/project-structure.md#3. Project Structure]
  • Install Tailwind CSS and PostCSS config for Nuxt; enable PrimeVue compatibility via utilities as needed. [Source: architecture/tech-stack.md#3. Tech Stack (Revised)]
  • Verify styles compile and are effective in a sample page.

• PrimeVue verification and demo

  • Render a PrimeVue Button and Dialog to confirm module, theme, and ripple settings are applied.
  • Ensure SSR produces no client-only errors in logs. [Source: architecture/component-standards.md#4. Component Standards]

• Testing scaffolding

  • Ensure Vitest and @vue/test-utils are configured.
  • Add example component and composable tests alongside sources with .spec.ts files. [Source: architecture/testing-requirements.md#8. Testing Requirements]

Dev Notes

• Tech Stack

  • Nuxt 4 as full-stack framework; Prisma ORM; PostgreSQL DB; Docker Compose for local environment. [Source: architecture/tech-stack.md#3. Tech Stack (Revised)]

• Project Structure

  • Monorepo layout integrates app/ (Nuxt), server/ (Nitro APIs), and prisma/ (ORM). Key files: nuxt.config.ts, docker-compose.yml, prisma/schema.prisma. [Source: architecture/unified-project-structure.md#6. Unified Project Structure]
  • SCSS structure and global import via nuxt.config.ts css array; partials under app/assets/scss/. [Source: architecture/project-structure.md#3. Project Structure]

• Component Standards

  • Use <script setup lang="ts">, organize code sections (imports, props/emits, state, computed, lifecycle, methods). Follow naming conventions: components in PascalCase, composables useX. [Source: architecture/component-standards.md#4. Component Standards]

• Testing Requirements

  • Vitest for unit tests; @vue/test-utils for component tests. Place tests adjacent to source files with .spec.ts. [Source: architecture/testing-requirements.md#8. Testing Requirements]

• Data Models

  • PRD requires tables for "Main Ledger" and "Registry". No specific schema is defined in architecture docs; define pragmatic initial fields to satisfy PRD and future extensibility. [Source: prd/epic-1-the-foundation-genesis-citizen-zero.md#Story 1.1]

• Previous Story Insights

  • None (this is the first story).

• API Specifications

  • Not in scope for this story; focus on DB readiness and app boot.

• Technical Constraints

  • Node 20+, Nuxt 4, SSR-safe usage of Prisma on server side. Ensure .env is not committed.

Project Structure Notes

• The current repository already contains a Nuxt 4 app and modules configured in nuxt.config.ts (PrimeVue and Prisma present). For AC 1, verify baseline instead of creating a brand-new project in this repo.
• docker-compose.yml does not exist yet at the repo root — this story will create it. [Source: architecture/unified-project-structure.md#6. Unified Project Structure]
• server/ directory is not present yet; Nuxt server routes (e.g., server/api/health.get.ts) should be created per structure guidance. [Source: architecture/unified-project-structure.md#6. Unified Project Structure]
• prisma/schema.prisma currently defines User and Post models (baseline). This story introduces tables for "Main Ledger" and "Registry" per PRD 1.1 — add new models/migrations (or refactor if directed by product) without breaking existing code paths.
• Prisma Client output is customized to app/generated/prisma. This can conflict with default imports and @prisma/nuxt. Unify by removing the custom output (preferred) or updating all usages consistently.
• Ensure a single Prisma client strategy: either the module composable or lib/prisma.ts singleton — not both, to avoid multiple instances during HMR.

Testing

• Add unit tests for:
  • Prisma connectivity helper or health endpoint returning DB status.
  • A sample component using PrimeVue Button to ensure render and interaction.
• Place tests next to sources with .spec.ts. [Source: architecture/testing-requirements.md#8. Testing Requirements]

Change Log

Date	Version	Description	Author
2025-09-01	v1	Initial draft created from PRD and Architecture docs	Scrum Master

Dev Agent Record

• Agent Model Used:
• Debug Log References:
• Completion Notes List:
• File List:

QA Results

• Status: PASS with CONCERNS
• Notes:
  • AC1 (Nuxt 4 baseline): Verified. nuxt.config.ts includes required modules (@primevue/nuxt-module, @prisma/nuxt, i18n). Project boots expectedly per structure; monorepo note satisfied by current repo layout.
  • AC2 (Docker Compose): docker-compose.yml present with postgres and app, health checks configured. Concerns:
    • app service does not expose port 3000; add ports: ["3000:3000"] for local access.
    • .env.example leaves DATABASE_OPEN_PORT blank while compose maps ${DATABASE_OPEN_PORT}:5432; define a default (e.g., 5432) or document required value to prevent startup errors.
  • AC3 (DB connectivity): server/api/health.get.ts performs await prisma.$queryRaw\SELECT 1`vialib/prisma.ts`. Evidence indicates connectivity path exists; recommend adding an integration test or run validation to confirm live connection.
  • AC4 (Schema & migrations): prisma/schema.prisma defines MainLedger and Registry; migration 20250901120752_init creates both tables and indexes. Verified.
  • AC5 (SCSS & Tailwind): SCSS structure present under app/assets/scss/ and included in nuxt.config.ts; Tailwind configured in tailwind.config.ts with app/assets/css/tailwind.css included. Verified.
  • PrimeVue demo & SSR: PrimeButtonDemo.vue renders Button and Dialog. Component test PrimeButtonDemo.spec.ts passes for click interaction. Suggest adding a keyboard activation test (Enter) and verifying SSR logs during a dev run for client-only warnings.
  • Testing scaffolding: Vitest setup present; example unit tests exist (test/unit/health.spec.ts, component spec). Verified.
  • Prisma client strategy: Both @prisma/nuxt (module enabled) and lib/prisma.ts singleton coexist. To avoid multiple clients during HMR, choose one approach. Since code imports lib/prisma.ts, recommend removing @prisma/nuxt from modules (or switch fully to usePrismaClient() and remove lib/prisma.ts).
  • Nuxt modules hygiene: nuxt.config.ts includes both @nuxt/test-utils and @nuxt/test-utils/module; keep only @nuxt/test-utils/module to avoid duplication.
  • A11y spot-check: Button includes type="button" and keyboard handler; html lang set in app.head. No blocking a11y issues noted for this scope.
  • Google Fonts: Using @nuxtjs/google-fonts. Ensure preconnect is active (module typically injects it); verify in head during runtime.
  • Gate Decision: PASS with CONCERNS. Provide qa.qaLocation to emit gate file at qa.qaLocation/gates/epic-1.1-project-initialization-main-ledger.yml; otherwise, we can default to docs/qa/gates/ if approved.