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\`` via `lib/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.