SYSTEM/docs/architecture/high-level-architecture.md

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

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

---