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

Story 1.1: Project Initialization & The Main Ledger

Status

Approved

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:
• Notes: