# sourcenetwork/defradb architecture

> Architecture diagram of the GitHub repository sourcenetwork/defradb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sourcenetwork/defradb
- Repository: https://github.com/sourcenetwork/defradb

## Overview

##### Main Components

a. Core Components:
- HTTP API Layer (port 9181)
- P2P Network Layer (port 9171)
- Query Engine (DQL)
- Storage Layer (BadgerDB)
- Schema Management
- Access Control System (ACP)
- Key Management System
- MerkleCRDT Engine

b. External Interfaces:
- GraphQL API Endpoint
- CLI Client Interface
- P2P Network Interface
- Backup/Restore Interface

**[HTTP/GraphQL API] --- [CLI Client] --- [P2P Network Interface]**

**[Query Engine (DQL)] --- [Schema Manager] --- [Access Control]**

**[MerkleCRDT Engine] -------- [Core DB] ----- [Key Management]**

**[BadgerDB Storage] --- [P2P Sync] --- [Backup/Restore]**

##### Connection Types

- Double lines: Data flow

##### Key Interactions to Highlight

a. Data Flow:
- Client requests through HTTP/GraphQL API
- Query processing through DQL engine
- Storage operations in BadgerDB
- P2P synchronization of updates
- Access control checks

b. Security Flow:
- Key management for encryption
- Access control policy enforcement
- P2P authentication

##### Component Details

Annotations for key components:

HTTP API:
- Port: 9181
- Endpoints: /api/v0/graphql
- CORS support
- Optional TLS

P2P Network:
- Port: 9171
- PubSub peering
- Replicator peering
- Document synchronization

Storage:
- BadgerDB backend
- MerkleCRDT structure
- Backup/restore capability

##### Additional Elements

Callouts for:
- Configuration options
- Default ports
- Key file locations
- Security considerations
- Scaling capabilities

##### Implementation Notes

- The modular nature of the system
- Security integration points
- Extensibility options
- Data flow patterns
- Synchronization mechanisms

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        HTTP[HTTP/GraphQL API]:::api
        CLI[CLI Client]:::client
        P2P[P2P Network Interface]:::p2p
        Client[Client Library]:::client
    end

    subgraph Core
        QE[Query Engine]:::core
        SM[Schema Manager]:::core
        AC[Access Control]:::security
        KM[Key Management]:::security
        ME[MerkleCRDT Engine]:::core
        DB[Core Database]:::core
        EV[Event System]:::core
        EN[Encryption System]:::security
    end

    subgraph Storage
        BD[BadgerDB Storage]:::storage
        PS[P2P Sync]:::p2p
        BR[Backup/Restore]:::storage
    end

    %% Client Layer Connections
    HTTP --- CLI
    CLI --- P2P
    HTTP --- Client
    
    %% Core to Client Connections
    HTTP --> QE
    CLI --> QE
    P2P --> PS
    
    %% Core Layer Connections
    QE --- SM
    SM --- AC
    ME --- DB
    DB --- KM
    QE --- ME
    DB --- AC
    DB --- EV
    KM --- EN
    
    %% Storage Layer Connections
    DB --- BD
    PS --- BD
    BR --- BD
    
    %% Click Events
    click HTTP "https://github.com/sourcenetwork/defradb/tree/develop/http"
    click P2P "https://github.com/sourcenetwork/defradb/tree/develop/net"
    click QE "https://github.com/sourcenetwork/defradb/tree/develop/internal/planner"
    click BD "https://github.com/sourcenetwork/defradb/tree/develop/datastore/badger/v4"
    click SM "https://github.com/sourcenetwork/defradb/tree/develop/internal/db/description"
    click AC "https://github.com/sourcenetwork/defradb/tree/develop/acp"
    click KM "https://github.com/sourcenetwork/defradb/tree/develop/keyring"
    click ME "https://github.com/sourcenetwork/defradb/tree/develop/internal/merkle/crdt"
    click HTTP "https://github.com/sourcenetwork/defradb/tree/develop/internal/request/graphql"
    click CLI "https://github.com/sourcenetwork/defradb/tree/develop/cli"
    click BR "https://github.com/sourcenetwork/defradb/tree/develop/cli/backup"
    click DB "https://github.com/sourcenetwork/defradb/tree/develop/internal/db"
    click Client "https://github.com/sourcenetwork/defradb/tree/develop/client"
    click EN "https://github.com/sourcenetwork/defradb/tree/develop/internal/encryption"
    click EV "https://github.com/sourcenetwork/defradb/tree/develop/event"

    %% Styles
    classDef api fill:#2374ab
    classDef client fill:#2374ab
    classDef core fill:#57a773
    classDef security fill:#ed474a
    classDef storage fill:#ffd151
    classDef p2p fill:#9067c6

    %% Legend
    subgraph Legend
        API[API Components]:::api
        CORE[Core Components]:::core
        SEC[Security Components]:::security
        STOR[Storage Components]:::storage
        P2PC[P2P Components]:::p2p
    end
```
