SYSTEM/docs/_archive/v1.0/prd.md

1. Goals and Background Context

Goals

Based on our brief, the primary goals for the MVP are:

• To establish a fully functional, self-hosted system that replaces informal financial tracking with a trusted, cryptographically secure ledger.
• To achieve complete adoption by all members of the initial "Община" (community).
• To ensure every transaction is immutable, auditable, and requires the consensus of the participants involved.
• To create a system that is not only functional but also engaging and fast for simple, everyday tasks.

Background Context

The core problem is that the current methods of managing shared domestic finances (like chat groups or spreadsheets) are inefficient, prone to error, and lack transparency. This creates friction and mental overhead for a group of friends living together. Project SYSTEM aims to solve this by providing a single, reliable source of truth that automates calculations, enforces fairness through cryptographic signatures, and introduces a unique, engaging user experience tailored to the community's culture.

Change Log

Date	Version	Description	Author
2025-08-31	1.0	Initial PRD draft	PM (John)

---

2. Requirements

Functional

1. FR1: System Initialization: The system must provide an interface for the first user ("Initiator") to create the "Община" and generate their initial cryptographic key pair.
2. FR2: Citizen Onboarding: The Initiator must be able to generate a unique, single-use invitation link to onboard new "Citizens". The onboarding process must include key pair generation and profile creation in the "Registry".
3. FR3: Optional Key Vault: During onboarding, a new "Citizen" must have the option to create a login/password account to store their private key in the server-side "Vault".
4. FR4: Immutable Ledger: Every state-changing action within the system (e.g., creating a Cell, joining, confirming payment) must be recorded as a new, cryptographically signed transaction in "The Main Ledger". The system must not allow direct modification or deletion of past transactions.
5. FR5: Cell Creation: Any "Citizen" must be able to create a financial "Cell" for a "Common Good", specifying the goal and the required items/costs ("Executor" roles).
6. FR6: Cell Participation: "Citizens" must be able to join a "Cell" as either an "Executor" (committing to purchase an item) or a "Consumer" (sharing the cost of the "Common Good").
7. FR7: Real-Time Calculation: The system must automatically and transparently calculate and display the financial obligations between all "Consumers" and "Executors" of a "Cell" as participants join or leave.
8. FR8: Payment Confirmation: An "Executor" must have the ability to sign a transaction confirming the receipt of payment from a specific "Consumer" for a specific "Cell".
9. FR9: Social Key Recovery: A "Citizen" who uses the "Vault" and has forgotten their password must be able to initiate a recovery process that requires cryptographic confirmation from a quorum of other "Citizens" (1 confirmation if <=4 members; 2 confirmations if >=5 members).

Non-Functional

1. NFR1: Performance on Embedded Hardware: The entire system (backend and database) must be optimized to run efficiently on a Raspberry Pi (Model 4 or newer recommended).
2. NFR2: High-Trust Environment Security: While designed for a trusted, private network, the application must include baseline web security practices (e.g., CSRF protection, secure headers). Direct database access should not be exposed.
3. NFR3: Cryptographic Integrity: All transactions must be signed using the Ed25519 algorithm or a similarly secure and lightweight standard. The integrity of the ledger's chain (verified by linking transaction hashes) must be maintained.
4. NFR4: Multi-Currency Support: The system must be able to handle calculations and record transactions in multiple fiat currencies (e.g., UAH, PLN, USD), with the currency specified at the "Cell" or "Plan" level.
5. NFR5: Internationalization (i18n) Readiness: The frontend architecture must be built to support multiple languages, even if the MVP only includes one language pack.
6. NFR6: Usability: The user interface for common, simple actions (like creating a quick "Cell") must be low-friction and require a minimal number of steps to encourage daily use.

---

3. User Interface Design Goals

Overall UX Vision

The user experience of SYSTEM should feel like interacting with a reliable, slightly mysterious, but ultimately transparent terminal or government console. The design must build trust by visualizing the cryptographic processes (e.g., showing transaction hashes, signed confirmations) without overwhelming the user. The primary goal is clarity and efficiency: a Citizen should always understand what's happening, what is required of them, and trust the integrity of the data presented. The overall aesthetic should lean into the thematic, "dystopian/communistic" vibe in a subtle, engaging way.

Key Interaction Paradigms

• Low-Friction for Common Tasks: Creating a simple "Cell" should be achievable in a few clicks. The interface should be fast and responsive.
• Seamless Signing: The process of signing transactions with the private key should be as unobtrusive as possible, perhaps by "unlocking" a session with the key rather than confirming every single action.
• Visual Trust: The UI should use visual cues to signify the status of data – e.g., a "finalized" transaction looks solid and permanent, while a "pending" transaction (in "Mushroom Mode") might appear hazy or watermarked.

Core Screens and Views

For the MVP, the following core screens are necessary:

• Onboarding/Setup Screen: For the first user to create the "Община" and for new Citizens to join via an invite link.
• Dashboard/Main View: A central hub showing all active "Cells" and "Plans" requiring the user's attention or participation. It should clearly display the user's current financial state (what they owe, what is owed to them).
• "Cell" Detail View: A screen showing all information for a single "Cell": the "Common Good", all "Executors" and "Consumers", payment status for each participant, and the transaction history from "The Main Ledger".
• "Cell" Creation Form: A simple, guided form to create a new "Cell".
• Profile/Keys Management View: A section where a "Citizen" can view their public key and manage their optional "Vault" account.

Accessibility: WCAG AA

The application should strive to meet WCAG 2.1 Level AA compliance to ensure it is usable by people with a wide range of disabilities.

Branding

The branding will be built around the chosen thematic elements of retro-futuristic communism and dystopia. This should be reflected in:

• Terminology: Using "Citizen," "Cell," "Common Good," "Five-Year Plan" consistently throughout the UI.
• Color Palette: A limited, functional color palette, perhaps with one striking accent color (e.g., red).
• Typography: Potentially a monospaced or "terminal-like" font for key data elements to enhance the console feel.

Target Device and Platforms: Web Responsive

The primary platform is a responsive web application that works seamlessly on both desktop and mobile browsers. A mobile-first design approach is recommended.

---

4. Technical Assumptions

Repository Structure: Monorepo

The project will be developed within a single monorepo. This approach is chosen to simplify dependency management and ensure consistency between the frontend and backend components, especially since they will be tightly coupled and share types and logic.

Service Architecture

For the MVP, the backend will be a Monolith. This simplifies development, deployment, and hosting on a single Raspberry Pi. The architecture should be internally modular to allow for potential future extraction of services if needed, but the initial deployment will be a single service.

Testing Requirements

The project requires a robust testing strategy focused on data integrity. The minimum requirement is Unit + Integration Testing.

• Unit Tests: Every individual function, especially cryptographic helpers and business logic calculators, must be covered by unit tests.
• Integration Tests: These are critical to validate the end-to-end flow of transactions within "The Main Ledger". Tests must cover scenarios like: creating a "Cell", adding participants, confirming payments, and verifying that the final calculated state is correct.

Additional Technical Assumptions and Requests

• Hosting: The entire application must be deployable and performant on a Raspberry Pi (Model 4 or newer). Deployment will be managed via Docker Compose.
• Core Tech Stack: The primary technology stack is Nuxt 4 (Vue 3) for the frontend and PostgreSQL for the database. The backend can be implemented using Nuxt 4's server capabilities.
• Styling: Styling will be implemented using SCSS and Tailwind CSS. A component framework (e.g., Nuxt UI, PrimeVue) is anticipated and will be chosen during the architecture phase.
• Cryptography: Transaction signing will use the Ed25519 algorithm or a similar lightweight, secure standard. The client is responsible for signing transactions unless the user opts into the server-side "Vault".
• Internationalization (i18n): The frontend application must be architected with i18n support from the ground up, even though the MVP will only ship with a single language pack.
• API Design: The API should be designed internally. No requirement for a public-facing REST/GraphQL API in the MVP, as the frontend and backend are tightly coupled.

---

5. Epic List

Here is the proposed high-level list of epics required to deliver the MVP. They are sequenced to build upon each other, ensuring a solid foundation is established first.

1. Epic 1: The Foundation - "Община" Genesis & Citizen Zero: Establish the absolute core of the system. This includes project setup, the database schema for the Ledger, and the complete, secure onboarding flow for the very first "Citizen" (the Initiator). The goal is a running application that can support a single user.
2. Epic 2: Community Expansion & The First "Cell": Focus on growing the "Община". This epic introduces the invitation system for new "Citizens" and implements the entire lifecycle of a financial "Cell" — from creation, participation by Consumers and Executors, to final payment confirmations. The goal is to have a fully functional system for managing one-time shared expenses.
3. Epic 3: The "Vault" & Social Recovery: Introduce the optional "Vault" feature. This includes creating the login/password mechanism for server-side key storage and implementing the crucial social recovery flow, where Citizens can approve a recovery request for another user. The goal is to add a layer of user-friendliness and safety for key management.

---

6. Epic 1: The Foundation - "Община" Genesis & Citizen Zero

Epic Goal: To establish the absolute core of the system. This includes the initial project setup, the database schema for "The Main Ledger", and the complete, secure onboarding flow for the very first "Citizen" (the Initiator). The ultimate goal of this epic is a running, deployable application that can securely support a single, authenticated user, creating the foundation for all future functionality.

Story 1.1: Project Initialization & The Main Ledger

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 new 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.

Story 1.2: Genesis - First Citizen Creation

As a first-time user (Initiator), I want to be guided through creating a new "Община" and my "Citizen" identity, so that I can become the first registered member and start using the system.

Acceptance Criteria:

1. When the application is launched in an empty state (no Citizens in the Registry), it must display a "Create Община" welcome screen.
2. The user is guided through a process that generates a new Ed25519 public/private key pair on the client-side.
3. The application must present the newly generated private key to the user for them to copy and save, displaying a prominent warning about the importance of keeping it secure and the consequences of its loss.
4. The user must be able to provide a name, which will be associated with their new public key in the "Registry".
5. Upon submission, a CITIZEN_CREATED transaction, signed with the new private key, must be successfully recorded as the first entry in "The Main Ledger".

Story 1.3: Authenticated Session & Dashboard Placeholder

As a newly created Initiator, I want my session to be securely authenticated using my private key, so that I can access the main application interface and perform actions on behalf of my "Citizen" identity.

Acceptance Criteria:

1. After successfully creating a "Citizen" identity, the user is automatically redirected to a main dashboard view.
2. The private key must be securely stored for the duration of the browser session in a script-accessible, non-persistent manner (e.g., in-memory variable).
3. The main dashboard must be a protected route, inaccessible to unauthenticated users.
4. The dashboard must display a simple welcome message that includes the "Citizen's" name from the "Registry" to confirm successful authentication.
5. Any future actions initiated from the UI must be able to access the session's private key to sign transactions.

---

7. Epic 2: Community Expansion & The First "Cell"

Epic Goal: To transform the single-user system into a multi-user "Община" and to implement the core functionality of managing shared finances through "Cells". After this epic, the system will be fully capable of handling the entire lifecycle of a one-time shared expense, from initiation to completion, for a community of two or more "Citizens".

Story 2.1: Citizen Invitation System

As an Initiator, I want to generate a secure, single-use invitation link, so that I can invite new "Citizens" to join my "Община".

Acceptance Criteria:

1. A logged-in "Citizen" (initially, only the Initiator) must have a "Generate Invitation" button on the dashboard.
2. Clicking the button generates a unique, single-use URL.
3. The system must store a record of the generated invitation token to validate it later.
4. The user interface must provide an easy way to copy the generated link.
5. Once an invitation link has been successfully used, it must be invalidated and cannot be used again.

Story 2.2: Onboarding via Invitation

As a new user, I want to be able to join an "Община" using an invitation link, so that I can become a "Citizen" and participate in shared activities.

Acceptance Criteria:

1. Accessing a valid invitation URL must present the new user with the "Citizen" creation screen.
2. The onboarding process must be identical to the "Genesis" flow (Story 1.2), including key generation and profile creation in the "Registry".
3. Upon successful creation, the new "Citizen" is added to the "Община" and can log in.
4. Attempting to access an invalid or already-used invitation URL must show a clear error message.

Story 2.3: "Cell" Creation

As a "Citizen", I want to create a new financial "Cell" for a "Common Good", so that I can initiate a collection of funds for a shared expense.

Acceptance Criteria:

1. The main dashboard must have a "Create Cell" button.
2. The creation form must allow the user to specify the "Common Good" (the purpose, e.g., "Суп").
3. The form must allow the user to define one or more "Executor" roles, including the item to be purchased and its estimated cost (e.g., "Мясо", 100 UAH).
4. Submitting the form must create a new CELL_CREATED transaction in "The Main Ledger".
5. The newly created "Cell" must appear on the main dashboard in an "Open" state.

Story 2.4: Participating in a "Cell"

As a "Citizen", I want to be able to join an existing "Cell" as either an "Executor" or a "Consumer", so that I can take part in the shared expense.

Acceptance Criteria:

1. In the "Cell" detail view, a "Citizen" can choose to become an "Executor" for an unassigned item.
2. Any "Citizen" (including "Executors") can join the "Cell" as a "Consumer".
3. When a "Citizen" joins, the system must re-calculate and display the updated debts for all "Consumers" to all "Executors".
4. Each act of joining (as Executor or Consumer) must be recorded as a distinct, signed transaction in "The Main Ledger".

Story 2.5: Payment Confirmation

As an "Executor", I want to be able to confirm that I have received a payment from a "Consumer", so that their debt is officially cleared in the system.

Acceptance Criteria:

1. In the "Cell" detail view, an "Executor" must see a list of "Consumers" who owe them money.
2. Next to each "Consumer's" name, there must be a "Confirm Payment" button.
3. Clicking the button must create a PAYMENT_CONFIRMED transaction, signed by the "Executor's" private key, which includes the IDs of both the "Consumer" and "Executor".
4. After confirmation, the UI must immediately update to show that the specific debt is cleared.

---

8. Epic 3: The "Vault" & Social Recovery

Epic Goal: To mitigate the primary risk of a decentralized identity system by introducing the optional "Vault" — a user-friendly, server-side storage for a Citizen's private key, secured by a traditional login/password. This epic will also implement the social recovery mechanism, allowing Citizens to regain access to their Vault-stored key with the help of their peers, thus adding a critical layer of safety and usability.

Story 3.1: The "Vault" Opt-In

As a new or existing "Citizen", I want the option to create a "Vault" account (login/password) and store an encrypted copy of my private key on the server, so that I have a backup and a way to use the SYSTEM if I don't have my primary key file with me.

Acceptance Criteria:

1. During the onboarding process (Story 2.2), after the private key is presented to the user, a new step must offer to create a "Vault" account.
2. The user must provide a password, which will be used to encrypt their private key on the client-side before it's sent to the server for storage. The server must only store the encrypted key and a salted hash of the password.
3. The UI must clearly explain that this is an optional convenience feature and that the most secure method is managing the key oneself.
4. A logged-in "Citizen" who did not opt-in during onboarding must have an option in their profile to create a "Vault" account later.

Story 3.2: Session Authentication via The "Vault"

As a "Citizen" with a "Vault" account, I want to be able to log into a new session using my login and password, so that the server can sign transactions on my behalf without me needing to provide my private key file.

Acceptance Criteria:

1. The main login screen must have a toggle or separate form for "Login with Vault" (username/password).
2. Upon successful login, the server must decrypt the user's private key using their password and hold it securely for the duration of the server-side session.
3. When the user performs a signable action, the request is sent to the server, which then signs the transaction with the session-stored private key before committing it to "The Main Ledger".
4. This flow must be distinct from the default client-side signing, where the server only receives an already-signed transaction.

Story 3.3: Social Recovery for The "Vault"

As a "Citizen" with a "Vault" account who has forgotten their password, I want to initiate a recovery process that other "Citizens" can approve, so that I can regain access to my encrypted private key.

Acceptance Criteria:

1. From the "Login with Vault" screen, there must be a "Forgot Password" link.
2. The user must identify themselves (e.g., by their name/public key) to initiate a recovery request. A RECOVERY_REQUESTED transaction is logged.
3. Other "Citizens" must see a notification about the pending recovery request on their dashboard.
4. The request UI must show who is requesting recovery and require a quorum of other "Citizens" to approve it by signing a RECOVERY_APPROVED transaction. (Quorum rule: 1 approval if <=4 members; 2 approvals if >=5 members).
5. Once the quorum is met, the server grants a temporary token, allowing the original user to reset their "Vault" password and re-encrypt their stored private key.

---