SYSTEM/docs/project-brief.md

Project Brief: SYSTEM

Executive Summary

Project SYSTEM is a self-hosted platform for communal living management, designed to bring cryptographic trust and transparency to shared domestic life. Initially focusing on financial coordination, it will manage shared expenses ("Cells") and recurring bills ("Plans") within a community ("Община"). The system's core is "The Main Ledger," an immutable, cryptographically-signed log of all transactions, ensuring a verifiable and auditable history. Identity is decentralized, based on public/private key pairs ("Citizens"), not traditional accounts, with an optional, socially-recoverable "Vault" for key storage. Key differentiators include multi-currency support, a unique dystopian/communistic theming for terminology (e.g., "Five-Year Plans" for long-term goals), and an innovative "Mushroom Mode" that allows for a "delayed finality" on decisions. Built on a Nuxt 4 + PostgreSQL stack, SYSTEM aims to be a comprehensive, modular, and engaging solution for resolving all domestic challenges.

Problem Statement

A cohesive group of friends living together ("Община") lacks a centralized, transparent, and trusted system for managing shared finances and domestic responsibilities. Current methods (e.g., chat groups, spreadsheets) are prone to confusion, manual calculation errors, and a lack of clear, auditable history for who paid for what and for whom. This creates unnecessary mental overhead and friction in coordinating everything from daily groceries ("Common Goods") to recurring shared bills ("Plans"). There is a need for a system that automates calculations, ensures every participant's consensus through undeniable cryptographic proof, and brings both structure and a unique, engaging thematic experience to communal life.

Proposed Solution

SYSTEM is a web application that replaces informal coordination with a structured, event-sourced platform. It operates on a single, trusted node (a self-hosted Raspberry Pi) and provides a single source of truth for all domestic agreements.

Core Concepts:

1. The Main Ledger: An immutable, append-only log (stored in PostgreSQL) where every action (creating a "Cell," joining, confirming payment) is a signed transaction. This ensures a permanent, auditable history that cannot be altered.
2. Citizen Identity: Users ("Citizens") are identified by their public/private key pair, not by username/password. This decentralizes identity and ties all actions directly to a cryptographic signature.
3. The Registry & The Vault: A user-friendly "Registry" maps public keys to user-provided names/avatars. The optional "Vault" provides a login/password system for securely storing the private key on the server, with a social recovery mechanism requiring confirmation from other Citizens.
4. Cells, Plans, and Five-Year Plans: A flexible structure for financial coordination:
   • Cells: One-time collections for a specific "Common Good" (e.g., groceries for a soup).
   • Plans: Recurring collections (e.g., monthly internet bill).
   • Five-Year Plans: Time-bound collections for a larger goal (e.g., saving for a new appliance).
5. Real-Time Coordination Flow: The system calculates who owes whom in real-time. The flow is: Consumer joins Cell -> System calculates debt -> Consumer pays Executor -> Executor cryptographically confirms payment -> Cell moves towards completion.
6. Mushroom Mode: A unique feature allowing for "delayed finality." Actions taken in this mode are logged as PENDING and can be superseded by a new action within a set time frame, before being finalized in the Ledger. This preserves immutability while allowing for human flexibility.
7. Push Notifications: A proactive notification system will inform Citizens of required actions (e.g., payment confirmations, recovery requests), ensuring the system is interactive and engaging.

Target Users

• Primary User Segment: The "Citizen"
  • Profile: A member of a small, co-living community of friends (2-10 people) who share expenses and responsibilities. They are generally tech-savvy but may not be cryptocurrency experts. They value transparency, fairness, and efficiency.
  • Behaviors: Currently uses ad-hoc methods like messaging apps and manual calculations to manage shared finances. Participates in group decisions and activities.
  • Needs: A simple way to initiate and track shared expenses, clarity on who owes whom, a single source of truth for financial history, and an engaging user experience that fits their community's culture.

Goals & Success Metrics

• Business/Project Objectives:
  • Successfully launch a self-hosted MVP that manages shared financial "Cells" and "Plans."
  • Achieve 100% adoption within the initial "Община."
  • Create a stable, immutable, and fully auditable "Main Ledger" of all transactions.
• User Success Metrics:
  • Reduce the time spent on manual calculations for shared expenses to zero.
  • Eliminate disagreements or confusion over who paid for what.
  • Users feel the system is trustworthy and transparent.
• Key Performance Indicators (KPIs):
  • Number of "Cells" created and successfully completed per month.
  • Average time from "Cell" creation to completion.
  • User engagement (daily/weekly active "Citizens").

MVP Scope

• Core Features (Must Have):
  • Onboarding & Identity: First-user setup to create the "Община." Invitation system for new "Citizens." Generation and management of key pairs, with the optional "Vault" for storage.
  • The Main Ledger: Functional implementation of the append-only, signed transaction log in PostgreSQL.
  • Cell Creation & Management: Ability for any "Citizen" to create a "Cell" for a "Common Good" with defined Executor roles.
  • Participation Flow: Citizens can join as "Executors" or "Consumers." The system must calculate and display all financial obligations in real-time.
  • Payment Confirmation: Executors can cryptographically confirm they've received funds from Consumers.
  • Core UI: A basic, functional interface to view, create, and interact with "Cells."
• Out of Scope for MVP:
  • "Plans" and "Five-Year Plans" (recurring and long-term collections).
  • "Mushroom Mode."
  • Advanced statistics, achievements, and gamification.
  • Management of non-financial resources (chores, shared items).
  • Full i18n support (interface will be in one primary language).
  • Push notifications (will be handled by manually checking the UI in MVP).

Post-MVP Vision

• Phase 2 Features: Introduce "Plans" and "Five-Year Plans." Implement "Mushroom Mode" and the push notification system. Develop the first iteration of the "Statistics" module.
• Long-term Vision: Expand SYSTEM to be a complete domestic operating system. Introduce modules for chore tracking, managing shared inventory (food, supplies), scheduling events, and resolving other communal living challenges, all logged within The Main Ledger.
• Expansion Opportunities: Create a distributable version that other communities can easily deploy for themselves.

Technical Considerations

• Platform Requirements: The backend will be self-hosted on a Raspberry Pi. The frontend will be a responsive web application accessible from any modern browser.
• Technology Preferences:
  • Frontend: Nuxt 4 (Vue 3).
  • Backend: Nuxt 4 server routes or a separate Node.js framework.
  • Database: PostgreSQL.
  • Cryptography: Standard libraries for key generation (e.g., crypto.subtle) and signing (e.g., noble-ed25519).
• Architecture Considerations:
  • Repository Structure: Monorepo.
  • Service Architecture: A single monolithic service for the MVP.
  • Security: Primary security is based on cryptographic signatures. The self-hosted nature implies a trusted network environment, but basic protections (e.g., against CSRF) should be in place. All keys stored in the server-side "Vault" must be encrypted at rest.

Constraints & Assumptions

• Constraints:
  • Must run efficiently on a Raspberry Pi.
  • The system is designed for a high-trust environment among a small group of users. It is not intended for public, untrusted networks.
• Key Assumptions:
  • Users will reliably save their private keys or opt-in to the "Vault."
  • The single-node (Raspberry Pi) is considered the single source of truth and is assumed to be secure and available.
  • The "social recovery" mechanism is sufficient for key recovery and preventing unauthorized access.

Risks & Open Questions

• Key Risks:
  • Key Management: A user losing their private key without using the "Vault" means a permanent loss of access. The UI must be extremely clear about this responsibility.
  • User Adoption: The unique terminology and crypto concepts, while engaging, could create a learning curve. The onboarding process must be exceptionally clear and simple.
  • Usability vs. Security: The process of signing every action could become tedious. The UI/UX must make this as seamless as possible (e.g., by holding the key in a browser session).
• Open Questions:
  • How will database schema migrations be handled in a self-hosted environment?
  • What is the most user-friendly way to present transaction signing to a non-technical user?