dsfx/docs/adr/0001-architecture-overview.md

# ADR-0001: Architecture Overview

## Status

Proposed

## Context

Our system is a self-hosted, privacy-focused file storage solution that enforces client-side encryption, robust file versioning, and decentralized peer-to-peer (P2P) interactions. Users must have full control over their data, with all operations being transparent, auditable, and reversible. In addition, our requirements demand that tests simulate real-world conditions such as network and disk latency and failures (see Functional Requirements FR-1, FR-4, FR-6 and Non-Functional Requirements NFR-2, NFR-6). This necessitates an architecture that not only provides a seamless user experience in normal operating conditions but also supports deterministic simulation of edge-case scenarios.

## Decision

We will adopt a _hybrid architecture_ that splits responsibilities between a client application and self-hosted server/P2P nodes. The design includes the following elements:

- **Client-Side Encryption and Processing:**
  All file encryption, decryption, partitioning, and version tracking is handled at the client. This ensures that files are secured (FR-1) before leaving the client and that the user remains in full control of their data. This design choice reinforces our core principle of user-controlled digital self-ownership.

- **Peer-to-Peer (P2P) Connectivity:**
  In addition to the client-server interaction, nodes will interact directly with one another via secure P2P connections (FR-4). These connections will leverage public-key based authentication, and support NAT traversal techniques to simulate and handle various networking conditions, including latency and intermittent disconnections (NFR-2).

- **Robust Replication and Redundancy:**
  A replication layer ensures that file chunks and versions are consistently available across multiple nodes (FR-5). The architecture supports automatic replication and rebalancing, even under simulated failure conditions such as disk or network outages (NFR-3, NFR-6).

- **Deterministic Simulation Capability:**
  The system will be designed as a non-I/O state machine at its core, allowing deterministic simulations of network delays, disk failures, and other real-world problems. This design supports our testing strategy, ensuring that performance, reliability, and auditability requirements are testable under controlled conditions (see overall testing strategy integrated in FR and NFR sections).

## Consequences

- **Advantages:**

  - **Enhanced Security:** By performing all sensitive operations on the client, our system better protects user data from unauthorized access.
  - **Improved Testing:** The non-I/O state machine design allows for deterministic simulations, making it easier to verify system behavior in the face of network and disk failures.
  - **Scalability and Resilience:** The decentralized approach via P2P interactions and replication supports scalability and reduces the risk of single points of failure.
  - **User Empowerment:** The architecture reinforces our commitment to privacy and user control by ensuring that all operations are transparent and fully auditable.

- **Trade-offs:**
  - **Complexity:** Introducing a hybrid model with P2P nodes increases the complexity of both development and maintenance compared to a purely centralized solution.
  - **Testing Overhead:** While deterministic simulations improve reliability, they require a robust testing framework that accurately models various failure conditions, potentially increasing development time.

## References to Requirements

- **Functional Requirements:**

  - FR-1: Secure file upload and download (ensuring client-side encryption).
  - FR-4: Peer-to-peer node interaction (supporting direct P2P connections).
  - FR-5: Replication and redundancy management (ensuring data integrity across nodes).
  - FR-6: User control and access management (ensuring auditability in all operations).

- **Non-Functional Requirements:**
  - NFR-2: Performance & responsiveness (accounting for simulated network and disk latency).
  - NFR-3: Scalability & capacity (ensuring robust operations under increasing loads).
  - NFR-6: Deployability & maintainability (facilitating deterministic simulation of deployment scenarios).

## Conclusion

The proposed hybrid architecture meets our overarching mission by ensuring privacy, user control, and robustness. It supports both regular operations and deterministic simulation of adverse conditions, satisfying our functional and non-functional requirements. This architecture lays a solid foundation to build a trustworthy, resilient system where every user interaction remains secure, fully auditable, and under the complete control of the user.