# classx/dark-matter architecture

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

- Interactive diagram: https://gitdiagram.com/classx/dark-matter
- Repository: https://github.com/classx/dark-matter

## Overview

##### Project Type and Purpose
- This is a single-binary, command-line vault utility named “Dark Matter,” written in Rust (Cargo project).
- Its purpose is to provide secure file storage (“vault”) by encrypting files with GPG, tracking them with an embedded SQLite database, and exposing a CLI for standard file‐management operations (add, list, update, remove, export) plus key validation.

##### Main Components
a. User / Terminal
- The user invokes commands in a shell.
b. Dark Matter CLI (Rust Binary)
- Argument parsing & dispatch
- Core vault logic orchestrator
- Sub-components (could be drawn as internal modules/layers):
- Encryption Module (interfaces with GPG/GPGME)
- Database Module (interacts with SQLite)
- Filesystem Module (reads/writes vault directory)
c. GPG Subsystem
- External service (GPG or GPGME library) that performs actual encryption/decryption and key management.
d. SQLite Database
- Embedded file ‘dark_matter.db’ inside vault directory storing metadata: file versions, timestamps, key hashes.
e. Vault File Store (Filesystem)
- Directory containing the encrypted file blobs.

##### Relationships and Data Flows
- User → CLI: issues commands (init, add, list, update, remove, export, validate).
- CLI → GPG Subsystem:
- init/validate: verify key existence & fingerprint
- /update/export: encrypt/decrypt file streams
- CLI → SQLite DB:
- init: create/open database schema
- /update/remove: insert/update/delete metadata records
- Query metadata
- CLI → Filesystem:
- /update: write encrypted files to vault
- export: read encrypted file, send to GPG for decryption, write plaintext out
- remove: delete encrypted file

##### Architectural Patterns and Principles
- Layered design (Presentation/CLI → Application core → Persistence/encryption).
- Single responsibility: each module handles one concern (CLI parsing vs. crypto vs. storage).
- External dependencies are abstracted behind Rust modules (GPGME crate or CLI calls).
- No network—local filesystem & embedded DB.

##### Technologies and Frameworks
- Rust (Cargo)
- GPG / GPGME (C library binding)
- SQLite (via rusqlite or similar crate)
- Standard filesystem APIs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph Legend
        direction TB
        A[Internal Modules]:::internal
        B[External Services]:::external
        C[Data Stores]:::datastore
        D[Documentation & Config]:::docs
    end

    %% User
    User["User (Shell)"]:::external

    %% Dark Matter CLI Binary
    subgraph "Dark Matter CLI Binary"
        direction TB
        Parser["CLI Parser"]:::internal
        VaultService["Vault Service"]:::internal
        CryptoAdapter["Crypto Adapter"]:::internal
        DBAdapter["DB Adapter"]:::internal
        FSModule["Filesystem Module"]:::internal
    end

    %% External Services and Data Stores
    GPG["GPG Subsystem"]:::external
    SQLiteDB["SQLite DB\n(dark_matter.db)"]:::datastore
    VaultDir["Vault Directory\n(Encrypted Files)"]:::datastore

    %% Documentation & Config
    Cargo["Cargo.toml"]:::docs
    MainRs["src/main.rs"]:::docs
    Readme["README.md"]:::docs
    Gitignore[".gitignore"]:::docs
    License["LICENSE.txt"]:::docs

    %% Connections
    User -->|"commands\n(init, add, list,\nupdate, remove, export,\nvalidate)"| Parser
    Parser -->|"dispatch"| VaultService

    %% Vault Service flows
    VaultService -->|"encrypt(file)\ndecrypt(file)\nvalidate key"| CryptoAdapter
    CryptoAdapter -->|"encrypt/decrypt\noperations"| GPG
    VaultService -->|"INSERT/UPDATE/DELETE\nSELECT queries"| DBAdapter
    DBAdapter -->|"SQL operations"| SQLiteDB
    VaultService -->|"file I/O\nwrite/read/delete"| FSModule
    FSModule -->|"filesystem access"| VaultDir

    %% Click Events
    click MainRs "https://github.com/classx/dark-matter/blob/main/src/main.rs"
    click Cargo "https://github.com/classx/dark-matter/blob/main/Cargo.toml"
    click Readme "https://github.com/classx/dark-matter/blob/main/README.md"
    click Gitignore "https://github.com/classx/dark-matter/blob/main/.gitignore"
    click License "https://github.com/classx/dark-matter/blob/main/LICENSE.txt"

    %% Styles
    classDef internal fill:#D0E6FF,stroke:#0366d6,stroke-width:1px;
    classDef external fill:#FFEDD5,stroke:#D97706,stroke-width:1px;
    classDef datastore fill:#D1FAE5,stroke:#059669,stroke-width:1px;
    classDef docs fill:#E5E7EB,stroke:#6B7280,stroke-width:1px;
```
