docs(agile): initialize docs

docs/architecture/api-integration.md

@@ -0,0 +1,49 @@
+# 6. API Integration
+
+Since the project is a monolith where the frontend and backend are served by the same Nuxt instance, we will use the built-in `$fetch` utility for all API calls. This is the recommended, isomorphic way to handle data fetching in Nuxt 4.
+
+## Service Layer Pattern
+
+To keep components clean and organize API logic, we will use a "service layer" pattern. All API calls will be abstracted into functions within files in the `app/services` directory.
+
+**`app/services/cellService.ts` (Example Template)**
+```typescript
+// Using Nuxt's built-in $fetch
+import { $fetch } from 'ofetch';
+
+// Define types for API payloads and responses, ideally imported from a shared location
+interface Cell {
+  id: string;
+  // ... other properties
+}
+
+interface CreateCellPayload {
+  commonGood: string;
+  // ... other properties
+}
+
+const BASE_URL = '/api/cells'; // Internal API endpoint
+
+export const cellService = {
+  /**
+   * Fetches the details for a single Cell.
+   * @param id The ID of the Cell.
+   */
+  async getCellById(id: string): Promise<Cell> {
+    return await $fetch<Cell>(`${BASE_URL}/${id}`);
+  },
+
+  /**
+   * Creates a new Cell.
+   * @param payload The data for the new Cell.
+   */
+  async createCell(payload: CreateCellPayload): Promise<Cell> {
+    return await $fetch<Cell>(BASE_URL, {
+      method: 'POST',
+      body: payload,
+    });
+  },
+
+  // ... other methods like joinAsConsumer, confirmPayment, etc.
+};
+```

docs/architecture/api-specification-server-architecture.md

@@ -0,0 +1,75 @@
+# 5. API Specification & Server Architecture
+
+The application will not expose a public REST или GraphQL API. All communication between the frontend and backend will occur internally via **Nuxt 4 Server Routes**. This approach is secure, performant, and perfectly suited for a monolithic fullstack application.
+
+## Server Directory Structure (`server/`)
+
+The server-side logic will be organized as follows:
+
+```plaintext
+server/
+├── api/
+│   ├── cells/
+│   │   ├── index.post.ts       # Create a new Cell
+│   │   └── [id]/
+│   │       ├── index.get.ts    # Get Cell details
+│   │       └── join.post.ts    # Join a Cell (as consumer/executor)
+│   ├── citizens/
+│   │   ├── index.post.ts       # Create a new Citizen (onboarding)
+│   │   └── invite.get.ts       # Generate an invitation link
+│   └── vault/
+│       ├── index.post.ts       # Create a Vault account
+│       ├── login.post.ts       # Login via Vault
+│       └── recover.post.ts     # Initiate/approve social recovery
+├── middleware/
+│   └── auth.ts                 # Middleware to check Citizen authentication
+└── utils/
+    ├── prisma.ts               # Exports a singleton Prisma Client instance
+    └── crypto.ts               # Cryptographic helper functions
+```
+
+## Core API Endpoints (MVP)
+
+| Endpoint | Method | Description | Request Body | Response |
+| :--- | :--- | :--- | :--- | :--- |
+| `/api/citizens` | `POST` | Creates the first Citizen or a new one via invite. | `{ name, publicKey }` | `Citizen` |
+| `/api/citizens/invite` | `GET` | Generates a single-use invitation link. | (none) | `{ inviteUrl }` |
+| `/api/cells` | `POST` | Creates a new "Cell". | `{ commonGood, executors }` | `LedgerEntry` |
+| `/api/cells/[id]` | `GET` | Retrieves the full state of a "Cell". | (none) | `CellState` |
+| `/api/cells/[id]/join` | `POST` | Joins a "Cell" as Executor or Consumer. | `{ role, item? }` | `LedgerEntry` |
+| `/api/cells/[id]/confirm`| `POST` | Confirms payment from a Consumer. | `{ consumerKey }` | `LedgerEntry` |
+
+## Core Workflow: The Cryptographic Signing Process
+
+This sequence diagram illustrates the fundamental process for every action in the system.
+
+```mermaid
+sequenceDiagram
+    participant Browser as Citizen's Browser
+    participant NuxtServer as Nuxt Server / API
+    participant Prisma
+    participant Ledger as The Main Ledger (DB)
+
+    Browser->>Browser: 1. User performs action (e.g., clicks "Create Cell")
+    Browser->>Browser: 2. Prepare `payload` (e.g., { commonGood: "Суп" })
+    Browser->>Browser: 3. Get `previousHash` from last Ledger entry
+    Browser->>Browser: 4. Create `entryHash` from payload + previousHash
+    Browser->>Browser: 5. Sign `entryHash` with private key to get `signature`
+    Browser->>NuxtServer: 6. POST /api/cells (sends payload, publicKey, signature)
+
+    NuxtServer->>NuxtServer: 7. Receive request
+    NuxtServer->>NuxtServer: 8. Validate signature using sender's `publicKey`
+    alt Signature is Invalid
+        NuxtServer-->>Browser: 9a. Return 401 Unauthorized
+    else Signature is Valid
+        NuxtServer->>Prisma: 9b. Get latest `previousHash` from DB
+        NuxtServer->>NuxtServer: 10. Verify client's `previousHash` matches server's
+        NuxtServer->>Prisma: 11. `prisma.ledgerEntry.create(...)`
+        Prisma->>Ledger: 12. INSERT INTO "LedgerEntry"
+        Ledger-->>Prisma: 13. Return new entry
+        Prisma-->>NuxtServer: 14. Return new entry
+        NuxtServer-->>Browser: 15. Return new LedgerEntry (success)
+    end
+```
+
+---

docs/architecture/component-standards.md

@@ -0,0 +1,56 @@
+# 4. Component Standards
+
+To ensure consistency and maintainability, all Vue components created in this project must adhere to the following standards.
+
+## Component Template (`.vue` files)
+
+All components should follow the standard Vue 3 `<script setup>` syntax. This is the recommended modern approach by both Vue and Nuxt documentation.
+
+Here is a minimal template for a new component:
+```vue
+<script setup lang="ts">
+// 1. IMPORTS
+// e.g., import { ref } from 'vue';
+// e.g., import Button from 'primevue/button';
+
+// 2. PROPS & EMITS
+// e.g., const props = defineProps<{
+//   citizenId: string;
+// }>();
+// e.g., const emit = defineEmits(['updated']);
+
+// 3. STATE & COMPOSABLES
+// e.g., const count = ref(0);
+// e.g., const { citizen } = useCitizen();
+
+// 4. COMPUTED PROPERTIES & WATCHERS
+// ...
+
+// 5. LIFECYCLE HOOKS
+// ...
+
+// 6. METHODS
+// e.g., function signTransaction() { ... }
+</script>
+
+<template>
+  <!-- 
+    Component template. Use PrimeVue components and Tailwind CSS classes here.
+    e.g., <div class="p-4 border-round-md"> ... </div>
+  -->
+</template>
+
+<style scoped lang="scss">
+/* 
+  Component-specific SCSS goes here.
+  Global variables/mixins are available thanks to nuxt.config.ts.
+  e.g., .my-component { color: var(--primary-color); }
+*/
+</style>
+```
+
+## Naming Conventions
+
+*   **Components:** `PascalCase`. Files should match the component name (e.g., `CellDetailView.vue`).
+*   **Composables:** `camelCase` with a `use` prefix (e.g., `useLedger.ts`).
+*   **SCSS Variables:** `$kebab-case` (e.g., `$primary-accent-color`).

docs/architecture/database-architecture.md

@@ -0,0 +1,59 @@
+# 4. Database Architecture (Revised with Prisma)
+
+The database schema will be defined declaratively using the Prisma schema language in a single source of truth file: `prisma/schema.prisma`. Prisma will be responsible for generating SQL migrations and providing a type-safe client for all database interactions.
+
+## Prisma Schema (`prisma/schema.prisma`)
+
+```prisma
+// This is your Prisma schema file,
+// learn more about it in the docs: https://pris.ly/d/prisma-schema
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+// User-friendly metadata associated with a public key.
+model Registry {
+  publicKey   String    @id
+  citizenName String
+  avatarUrl   String?
+  isActive    Boolean   @default(true)
+  createdAt   DateTime  @default(now())
+}
+
+// The core, immutable data model.
+// Once a row is written, it is never updated or deleted.
+model LedgerEntry {
+  id                 BigInt    @id @default(autoincrement())
+  previousHash       String?
+  entryHash          String    @unique
+  citizenPublicKey   String
+  signature          String
+  actionType         String
+  payload            Json? // The actual data for the action, e.g., cell details
+  createdAt          DateTime  @default(now())
+
+  @@index([citizenPublicKey])
+  @@index([payload], name: "idx_ledger_payload_entity") // Example for indexing specific payload keys
+}
+```
+
+## Migrations Workflow
+
+Database migrations will be managed exclusively by Prisma Migrate.
+1.  **Development:** After any change to `schema.prisma`, a new migration will be created and applied using the command:
+    ```bash
+    npx prisma migrate dev --name <descriptive_migration_name>
+    ```
+2.  **Production:** Migrations will be applied during the deployment process using:
+    ```bash
+    npx prisma migrate deploy
+    ```
+This ensures that the database schema is always in sync with the Prisma schema definition.
+
+---

docs/architecture/deployment-architecture.md

@@ -0,0 +1,10 @@
+# 8. Deployment Architecture
+
+*   **Strategy:** The application will be deployed as a set of Docker containers orchestrated by `docker-compose`. This simplifies deployment on the target Raspberry Pi.
+*   **Process:**
+    1.  A `Dockerfile` will build the Nuxt application into a production-ready Node.js server.
+    2.  `docker-compose.yml` will define two services:
+        *   `app`: The Nuxt application built from the `Dockerfile`.
+        *   `db`: The official PostgreSQL image, with a persistent volume mounted to store the database data.
+    3.  Deployment consists of pulling the latest code, running `docker-compose up -d --build` on the Raspberry Pi.
+*   **Migrations:** Production migrations will be applied by running `npx prisma migrate deploy` inside the running `app` container or as part of the container's startup command.

docs/architecture/development-workflow.md

@@ -0,0 +1,13 @@
+# 7. Development Workflow
+
+1.  **Initial Setup:**
+    *   Clone the repository.
+    *   Create a `.env` file with the `DATABASE_URL`.
+    *   Run `docker-compose up -d --build` to start the PostgreSQL container and the Nuxt development server.
+2.  **Schema Changes:**
+    *   Modify `prisma/schema.prisma`.
+    *   Run `npx prisma migrate dev --name <migration-name>` to apply changes to the running database. Prisma Client will be auto-generated.
+3.  **Development:**
+    *   Develop Vue components in the `app/` directory.
+    *   Develop API endpoints in the `server/api/` directory.
+    *   The Nuxt dev server will provide hot-reloading for both frontend and backend changes.

docs/architecture/frontend-tech-stack.md

@@ -0,0 +1,14 @@
+# 2. Frontend Tech Stack
+
+This table reflects the choices made in the PRD and the user's template, solidifying the frontend technology stack.
+
+| Category | Technology | Version | Purpose & Rationale |
+| :--- | :--- | :--- | :--- |
+| Framework | **Nuxt** | `^4.0.3` | The core application framework, providing SSR, file-based routing, and a robust module ecosystem. |
+| UI Library | **PrimeVue** | `^4.3.7` | The primary component library. Chosen for its rich set of components and powerful theming capabilities. |
+| Theme | **PrimeUI Aura** | `^1.2.3` | The default theme preset for PrimeVue, providing a modern and clean aesthetic out of the box. |
+| Styling | **Tailwind CSS** | `^0.6.1` (primeui) | For utility-first styling, rapid prototyping, and responsive design. |
+| Styling | **SCSS (Sass)** | (via `sass` dev dep) | For structured styling, variables, mixins, and managing global styles and theme overrides. |
+| i18n | **@nuxtjs/i18n**| `10.0.6` | For future-proof internationalization, as required by the PRD. |
+
+---

docs/architecture/high-level-architecture.md

@@ -0,0 +1,43 @@
+# 2. High Level Architecture
+
+## Technical Summary
+
+Project SYSTEM is a monolithic, self-hosted web application built on the Nuxt 4 framework. The architecture is designed for efficiency and transparency, running on a Raspberry Pi. It features a Vue-based frontend interacting with a PostgreSQL database via Nuxt's server-side API routes. The core of the system is an immutable, event-sourced "Main Ledger" where every action is a cryptographically signed transaction, ensuring data integrity and auditability. Identity management is decentralized, based on public/private key pairs.
+
+## Platform and Infrastructure Choice
+
+*   **Platform:** Self-hosted on a user-provided **Raspberry Pi** (Model 4+).
+*   **Key Services:**
+    *   **Application Server:** **Nuxt 4** running in Node.js mode.
+    *   **Database:** **PostgreSQL**.
+    *   **Containerization:** The entire stack will be managed and deployed via **Docker Compose**. This ensures a consistent and reproducible environment.
+*   **Deployment Host and Regions:** Single host, located within the "Община's" private network.
+
+## Repository Structure
+
+*   **Structure:** **Monorepo**.
+*   **Monorepo Tool:** Not required for this level of simplicity. A single `package.json` at the root will manage all dependencies.
+*   **Package Organization:** A standard Nuxt 4 project structure will be used, as detailed in the Frontend Architecture. Server-side logic will reside within the `server/` directory.
+
+## High Level Architecture Diagram
+
+```mermaid
+graph TD
+    subgraph "Browser"
+        A[Citizen's Browser]
+    end
+
+    subgraph "Raspberry Pi (Docker Compose)"
+        B[Nuxt 4 Server]
+        C[PostgreSQL Database]
+
+        B -- "Serves Frontend" --> A
+        A -- "API Calls ($fetch)" --> B
+        B -- "Reads/Writes" --> C
+    end
+
+    style B fill:#2D3748,stroke:#fff,stroke-width:2px,color:#fff
+    style C fill:#4A5568,stroke:#fff,stroke-width:2px,color:#fff
+```
+
+---

docs/architecture/index.md

@@ -0,0 +1,38 @@
+# SYSTEM Fullstack Architecture Document
+
+## Table of Contents
+
+- [SYSTEM Fullstack Architecture Document](#table-of-contents)
+  - [1. Template and Framework Selection](template-and-framework-selection.md)
+    - [Change Log](template-and-framework-selection.md#change-log)
+  - [2. Frontend Tech Stack](frontend-tech-stack.md)
+  - [3. Project Structure](project-structure.md)
+  - [4. Component Standards](component-standards.md)
+    - [Component Template ( files)](component-standards.md#component-template-files)
+    - [Naming Conventions](component-standards.md#naming-conventions)
+  - [5. State Management](state-management.md)
+    - [State Management Template ()](state-management.md#state-management-template)
+  - [6. API Integration](api-integration.md)
+    - [Service Layer Pattern](api-integration.md#service-layer-pattern)
+  - [7. Routing](routing.md)
+  - [8. Testing Requirements](testing-requirements.md)
+  - [1. Introduction](introduction.md)
+    - [Starter Template or Existing Project](introduction.md#starter-template-or-existing-project)
+    - [Change Log](introduction.md#change-log)
+  - [2. High Level Architecture](high-level-architecture.md)
+    - [Technical Summary](high-level-architecture.md#technical-summary)
+    - [Platform and Infrastructure Choice](high-level-architecture.md#platform-and-infrastructure-choice)
+    - [Repository Structure](high-level-architecture.md#repository-structure)
+    - [High Level Architecture Diagram](high-level-architecture.md#high-level-architecture-diagram)
+  - [3. Tech Stack (Revised)](tech-stack.md)
+  - [4. Database Architecture (Revised with Prisma)](database-architecture.md)
+    - [Prisma Schema ()](database-architecture.md#prisma-schema)
+    - [Migrations Workflow](database-architecture.md#migrations-workflow)
+  - [5. API Specification & Server Architecture](api-specification-server-architecture.md)
+    - [Server Directory Structure ()](api-specification-server-architecture.md#server-directory-structure)
+    - [Core API Endpoints (MVP)](api-specification-server-architecture.md#core-api-endpoints-mvp)
+    - [Core Workflow: The Cryptographic Signing Process](api-specification-server-architecture.md#core-workflow-the-cryptographic-signing-process)
+  - [6. Unified Project Structure](unified-project-structure.md)
+  - [7. Development Workflow](development-workflow.md)
+  - [8. Deployment Architecture](deployment-architecture.md)
+  - [9. Security & Performance](security-performance.md)

docs/architecture/introduction.md

@@ -0,0 +1,13 @@
+# 1. Introduction
+
+This document outlines the complete fullstack architecture for Project SYSTEM, including the backend systems, frontend implementation, and their integration. It serves as the single source of truth for AI-driven development, ensuring consistency across the entire technology stack. This unified approach combines backend and frontend concerns to streamline development.
+
+## Starter Template or Existing Project
+
+*   **Decision:** The project is based on the custom Nuxt 4 starter template provided by the user. No external templates are used. The architecture will be built upon this existing foundation.
+
+## Change Log
+
+| Date | Version | Description | Author |
+| :--- | :--- | :--- | :--- |
+| 2025-08-31 | 1.0 | Initial Fullstack Architecture draft | Architect (Winston) |

docs/architecture/project-structure.md

@@ -0,0 +1,78 @@
+# 3. Project Structure
+
+Based on the Nuxt 4 documentation and the need to manage SCSS files effectively, the following directory structure will be adopted within the `app/` directory.
+
+```plaintext
+app/
+├── assets/
+│   └── scss/
+│       ├── base/
+│       │   ├── _reset.scss       # Optional: for CSS resets
+│       │   └── _typography.scss  # Base typography styles
+│       ├── components/
+│       │   └── _buttons.scss     # Example: Custom button styles
+│       ├── layout/
+│       │   └── _main.scss        # Main layout styles
+│       ├── themes/
+│       │   └── _aura-overrides.scss # Specific overrides for the Aura theme
+│       ├── utils/
+│       │   ├── _variables.scss   # Global SCSS variables (colors, spacing)
+│       │   └── _mixins.scss      # Global SCSS mixins
+│       └── main.scss             # Main entry file that imports all other SCSS partials
+│
+├── components/
+│   ├── common/
+│   │   └── AppHeader.vue         # Example of a globally used component
+│   └── specific/
+│       └── CellDetailView.vue    # Example of a view-specific component
+│
+├── composables/
+│   ├── useCitizen.ts             # Composable for managing Citizen identity
+│   └── useLedger.ts              # Composable for interacting with The Main Ledger
+│
+├── layouts/
+│   └── default.vue               # The default layout for the application
+│
+├── pages/
+│   ├── index.vue                 # Dashboard / Main View
+│   └── cell/
+│       └── [id].vue              # Cell Detail View (Dynamic Route)
+│
+├── plugins/
+│   └── primevue.ts               # Plugin to register PrimeVue components/services if needed
+│
+└── app.vue                       # Main application entry point
+```
+
+To make this SCSS structure work seamlessly, we will update `nuxt.config.ts` to automatically import our main SCSS file globally.
+
+**`nuxt.config.ts` modification:**
+```typescript
+export default defineNuxtConfig({
+  // ... other configs
+  css: ['~/assets/scss/main.scss'],
+  // ... other configs
+})
+```
+
+**`app/assets/scss/main.scss` content:**
+```scss
+// 1. Utilities (Variables, Mixins)
+@use 'utils/variables';
+@use 'utils/mixins';
+
+// 2. Base Styles
+@use 'base/reset';
+@use 'base/typography';
+
+// 3. Layout Styles
+@use 'layout/main';
+
+// 4. Component Styles
+@use 'components/buttons';
+
+// 5. Theme Overrides
+@use 'themes/aura-overrides';
+```
+
+---

docs/architecture/routing.md

@@ -0,0 +1,28 @@
+# 7. Routing
+
+Routing will be handled by Nuxt's file-based router. All pages will be created as `.vue` files in the `app/pages` directory.
+
+**Route Configuration Example (`app/pages/cell/[id].vue`)**
+```vue
+<script setup lang="ts">
+import { useRoute } from 'vue-router';
+
+const route = useRoute();
+const cellId = route.params.id as string;
+
+// Fetch cell data using the service
+const { data: cell, pending, error } = await useAsyncData(
+  `cell-${cellId}`,
+  () => cellService.getCellById(cellId)
+);
+</script>
+
+<template>
+  <div v-if="pending">Loading...</div>
+  <div v-else-if="error">Error loading Cell: {{ error.message }}</div>
+  <div v-else-if="cell">
+    <h1>{{ cell.commonGood }}</h1>
+    <!-- Display cell details here -->
+  </div>
+</template>
+```

docs/architecture/security-performance.md

@@ -0,0 +1,12 @@
+# 9. Security & Performance
+
+*   **Security:**
+    *   **Authentication:** Managed via cryptographic signatures. The server is stateless regarding authentication.
+    *   **Authorization:** All API endpoints inside `server/middleware/auth.ts` will verify the incoming signature against the `publicKey` to ensure the action is performed by the legitimate owner of the key.
+    *   **Secrets:** The `DATABASE_URL` will be managed via the `.env` file, which is excluded from version control.
+*   **Performance:**
+    *   The primary performance consideration is the Raspberry Pi environment. The monolithic Nuxt/PostgreSQL stack is chosen for its low resource overhead compared to more complex microservice architectures.
+    *   Database queries will be optimized using indices as defined in the Prisma schema.
+    *   Frontend assets will be optimized by Nuxt's build process.
+
+---

docs/architecture/state-management.md

@@ -0,0 +1,40 @@
+# 5. State Management
+
+*   **Approach:** For the MVP, we will rely primarily on **Nuxt's built-in `useState` composable** for simple, shared, server-side-renderable state. This is the most lightweight and idiomatic approach for Nuxt 4. We will avoid installing a heavy external library like Pinia or Vuex until the application's complexity demonstrably requires it.
+*   **Structure:** Shared state composables will be located in the `app/composables/` directory.
+
+## State Management Template (`app/composables/useSomeState.ts`)
+
+```typescript
+import { useState } from '#app';
+
+// Example: Managing the current Citizen's session info
+interface CitizenSession {
+  name: string;
+  publicKey: string;
+  // NOTE: The private key should NOT be stored in a composable.
+  // It should be managed in a more secure, non-persistent way.
+}
+
+export const useCitizenStore = () => {
+  const citizen = useState<CitizenSession | null>('citizen', () => null);
+
+  const setCitizen = (newCitizen: CitizenSession) => {
+    citizen.value = newCitizen;
+  };
+
+  const clearCitizen = () => {
+    citizen.value = null;
+  };
+
+
+
+  return {
+    citizen,
+    setCitizen,
+    clearCitizen,
+  };
+};
+```
+
+---

docs/architecture/tech-stack.md

@@ -0,0 +1,9 @@
+# 3. Tech Stack (Revised)
+
+| Category | Technology | Version | Purpose & Rationale |
+| :--- | :--- | :--- | :--- |
+| **Fullstack Framework**| **Nuxt** | `^4.0.3` | Core framework for both frontend and backend (server routes). |
+| **Database ORM** | **Prisma** | `latest` | Next-generation ORM for type-safe database access and automated migrations. |
+| **Database** | **PostgreSQL** | `latest` | Robust, reliable SQL database managed by Prisma. |
+| **Deployment** | **Docker Compose**| `latest` | For containerizing and managing the application stack. |
+| ... | *(rest of the stack remains the same)* | ... | ... |

docs/architecture/template-and-framework-selection.md

@@ -0,0 +1,12 @@
+# 1. Template and Framework Selection
+
+*   **Framework:** The project is built on **Nuxt 4**, as specified in the provided `repomix-output.xml`.
+*   **UI Library:** The core component library is **PrimeVue**, with the **Aura** theme preset. This choice is confirmed in `nuxt.config.ts`.
+*   **Styling:** A hybrid approach using **Tailwind CSS** for utility-first styling and **SCSS** for global styles, variables, and complex component styling is adopted.
+*   **Starter Template:** The project is based on the custom template provided by the user. No external starter templates are used. This gives us full control but requires us to define the structure meticulously.
+
+## Change Log
+
+| Date | Version | Description | Author |
+| :--- | :--- | :--- | :--- |
+| 2025-08-31 | 1.0 | Initial Frontend Architecture draft | Architect (Winston) |

docs/architecture/testing-requirements.md

@@ -0,0 +1,7 @@
+# 8. Testing Requirements
+
+Testing is critical for ensuring the integrity of the system.
+*   **Unit Tests:** We will use **Vitest** for unit testing. Every composable and service function must have unit tests covering its logic.
+*   **Component Tests:** We will use **`@vue/test-utils`** to test individual Vue components. Tests should verify that components render correctly based on props and that they emit events when interacted with.
+*   **Test Location:** All test files will be located alongside the file they are testing, with a `.spec.ts` extension (e.g., `useLedger.spec.ts`).
+

docs/architecture/unified-project-structure.md

@@ -0,0 +1,33 @@
+# 6. Unified Project Structure
+
+This is the final monorepo structure that integrates the frontend (`app/`), backend (`server/`), and database (`prisma/`) components.
+
+```plaintext
+system/
+├── app/                      # Nuxt frontend application
+│   ├── assets/
+│   │   └── scss/
+│   ├── components/
+│   ├── composables/
+│   ├── layouts/
+│   ├── pages/
+│   └── ...
+├── prisma/                   # Prisma ORM configuration
+│   ├── migrations/
+│   │   └── .../migration.sql
+│   └── schema.prisma         # The single source of truth for the database
+├── server/                   # Nuxt server-side logic (API)
+│   ├── api/
+│   │   └── ...
+│   ├── middleware/
+│   └── utils/
+├── types/                    # Shared TypeScript types
+│   ├── citizen.ts
+│   ├── ledger.ts
+│   └── index.ts
+├── docker-compose.yml        # Defines and runs the multi-container stack
+├── Dockerfile                # For building the Nuxt application image
+├── nuxt.config.ts            # Nuxt configuration
+├── package.json
+└── tsconfig.json
+```