docs(agile): draft story 1.1

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

@@ -0,0 +1,121 @@
+# 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: