# zhaofengli/attic architecture

> Architecture diagram of the GitHub repository zhaofengli/attic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhaofengli/attic
- Repository: https://github.com/zhaofengli/attic

## Overview

##### Project Type & Purpose
- Attic is a self-hostable Nix Binary Cache server. Its primary function is to serve as a binary cache backed by an S3-compatible storage provider. Core goals include multi-tenancy, global deduplication, managed signing, and garbage collection.
- The project is written in Rust and is organized into multiple Cargo packages (attic, client, server, token) that collaboratively implement the caching server, the CLI client, token/authentication support, and shared libraries.

##### Main Architectural Components
- Attic Core Library ("attic" directory):
- Contains the core logic including API definitions, chunking, hashing, signing, Nix store bindings, and utility functionality.
- Modules are further split (e.g., src/api, src/chunking, src/error, src/nix_store) so that the underlying binary cache operations, deduplication, and signing logic are encapsulated here.
- Server ("server" directory):
- Implements the actual Nix binary cache server binary. Includes API endpoints (with multiple API versions under src/api/v1) handling operations like uploading paths, fetching missing paths, and binary cache management.
- Integrates with a database (see the database directory with migration files and entities) which maps tenants to cached content and maintains metadata.
- Manages HTTP access and other middleware components.
- Client ("client" directory):
- Provides a command-line tool for interacting with the server, handling tasks such as login, pushing binaries, cache commands, and configuration.
- Acts as the user-facing interface that triggers API requests to the server.
- Token ("token" directory):
- Contains logic for handling token operations, possibly for access control or managed signing, which is essential for securing the interactions.
- Additional Components:
- CI/Integration Testing & Documentation:
- .ci, GitHub workflows, integration-tests directories indicate a continuous integration pipeline.
- The book directory hosts user guides and reference materials, explaining how to deploy and use Attic.
- Build & Deployment Scripts:
- Files like shell.nix, flake.nix, and various Nix configurations suggest a reproducible build and deployment environment, including support for serverless platforms.

##### Relationships and Data Flow
- Client-to-Server Interaction:
- Server Internals:
- Inside the Server component, delineate the API handling (shown as separate modules such as API v1 endpoints).
- A connection from the Server to the shared Attic Core libraries for operations such as deduplication (via chunking & hashing) and for invoking the signing service.
- Database and Storage Interaction:
- A Database component which represents the persistent data store. Represent the server’s interactions with the database (for migrations, cache entity management, etc.).
- Token Handling:
- A Token Service/Module which may be used both by the Server (for signing or authentication) and by the Client if session tokens or API keys are managed.
- CI/CD Pipeline:

##### Expected Architectural Patterns
- Modularity: The decomposition into multiple Cargo packages (core library, server, client, token) clearly suggests adherence to modular design.
- API-first and Layered Architecture: The separation of API modules, middleware, storage, and helper libraries (e.g., for chunking, hashing) indicates clean layering.
- Self-Containment & Extensibility: Having separate directories for tests, docs, and integrations illustrates a maintainable and extensible system.

##### Final Touches
- Even if the components are highly interdependent (like the interactions between the core logic and different binaries), separating them clearly helps in understanding the architecture.
- Avoid over-cluttering; group related modules with clear boundaries (for example, all components under “Attic Core” can be grouped together, while “Client” remains distinct).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "Core Modules"
        AtticCore["Attic Core Library"]:::core
    end

    subgraph "Applications"
        Client["Client (CLI)"]:::service
        Server["Server"]:::service
        Token["Token Service/Module"]:::service
    end

    subgraph "External Services"
        Database["Database"]:::external
        S3Storage["S3-Compatible Storage"]:::external
    end

    subgraph "Infrastructure"
        CICD["CI/CD Pipeline"]:::infra
        Documentation["Documentation & User Guides"]:::docs
    end

    %% Relationships
    Client -->|"API_calls/commands"| Server
    Server -->|"deduplication&signing"| AtticCore
    Server -->|"auth/token_ops"| Token
    Client -->|"token_management"| Token
    Server -->|"queries/updates"| Database
    Server -->|"upload/download"| S3Storage
    CICD -->|"deploys/tests"| Server
    CICD -->|"deploys/tests"| Client
    CICD -->|"deploys/tests"| Token

    %% Click Events
    click AtticCore "https://github.com/zhaofengli/attic/tree/main/attic/"
    click Server "https://github.com/zhaofengli/attic/tree/main/server/"
    click Client "https://github.com/zhaofengli/attic/tree/main/client/"
    click Token "https://github.com/zhaofengli/attic/tree/main/token/"
    click Database "https://github.com/zhaofengli/attic/tree/main/server/src/database/"
    click S3Storage "https://github.com/zhaofengli/attic/blob/main/server/src/storage/s3.rs"
    click CICD "https://github.com/zhaofengli/attic/tree/main/.ci/"
    click Documentation "https://github.com/zhaofengli/attic/tree/main/book/"

    %% Styles
    classDef core fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef service fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef external fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef infra fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef docs fill:#d6eaf8,stroke:#333,stroke-width:2px;
```
