# intersectmbo/cardano-db-sync architecture

> Architecture diagram of the GitHub repository intersectmbo/cardano-db-sync, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/intersectmbo/cardano-db-sync
- Repository: https://github.com/intersectmbo/cardano-db-sync

## Overview

##### Main Components

a. External Components:
- Cardano Node (connected via Unix domain socket)
- PostgreSQL Database
- External Applications (read-only access)

b. Core Components:
- cardano-db-sync (main service)
- cardano-db (database interface layer)
- cardano-db-tool (database management)
- cardano-smash-server (pool metadata service)

##### Architecture Layers

a. Network Layer:
- Chain Sync Protocol Interface
- Local State Query Interface
- Unix Domain Socket Connection

b. Processing Layer:
- Block Processing
- Ledger State Management
- Transaction Processing
- Era-specific Handlers (Byron, Shelley, Alonzo, Babbage, Conway)

c. Database Layer:
- Schema Management
- Migration Handling
- Query Operations
- Data Validation

##### Data Flow Representation

- Data flow from Cardano Node → DB Sync
- Block/Transaction processing flow
- Database write operations
- Read queries from external applications

##### Component Details

a. Cardano DB Sync:
- Chain following mechanism
- Block processor
- State management
- Era-specific handlers
- Rollback handling

b. Database Layer:
- Schema versioning
- Migration management
- CRUD operations
- Validation rules

##### Key Interactions

Specific interactions for:
- Block synchronization
- State updates
- Database migrations
- External queries
- Pool metadata handling

##### Architectural Patterns

Highlight:
- Event-driven processing
- Pipeline processing
- State management
- Data validation
- Error handling

**[External Cardano Node] ←→ [Unix Socket]**
- ↓
**[Cardano DB Sync Core]**
- ↓         ↓         ↓
**[Block     [State    [Transaction**
**Processor]  Manager]  Processor]**
- ↓         ↓         ↓
**[Database Interface Layer]**
- ↓
**[PostgreSQL Database] ←→ [External Applications]**

Detailed annotations for:
- System requirements
- Data flow directions
- Component responsibilities
- Integration points
- Error handling paths
- Validation checkpoints

This design should emphasize the system's ability to:
- Follow the Cardano blockchain
- Maintain ledger state
- Process and store blockchain data
- Handle different blockchain eras
- Manage database schema evolution
- Support external application queries
- Handle rollbacks and chain reorganizations

Remember to maintain a balance between detail and clarity, focusing on the key architectural components while providing enough detail for implementation guidance.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph External
        Node[Cardano Node]:::external
        DB[(PostgreSQL Database)]:::storage
        Apps[External Applications]:::external
    end

    subgraph Network
        Socket[Unix Domain Socket]:::network
        ChainSync["Chain Sync Protocol"]:::network
        StateQuery["State Query Interface"]:::network

        click ChainSync "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db-sync/src/Cardano/DbSync/Sync.hs"
        click StateQuery "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db-sync/src/Cardano/DbSync/StateQuery.hs"
    end

    subgraph Core["Core Processing"]
        DBSync["Cardano DB Sync"]:::core
        Cache["Cache Manager"]:::core
        Rollback["Rollback Handler"]:::core

        click DBSync "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db-sync/src/Cardano/DbSync.hs"
        click Cache "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db-sync/src/Cardano/DbSync/Cache/"
        click Rollback "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db-sync/src/Cardano/DbSync/Rollback.hs"
    end

    subgraph Processing["Processing Layer"]
        BlockProc["Block Processor"]:::processing
        StateMan["Ledger State Manager"]:::processing
        TxProc["Transaction Processor"]:::processing
        EraHandlers["Era-specific Handlers"]:::processing

        click StateMan "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db-sync/src/Cardano/DbSync/Ledger/"
        click TxProc "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db-sync/src/Cardano/DbSync/Era/Shelley/Generic/Tx/"
        click EraHandlers "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db-sync/src/Cardano/DbSync/Era/"
    end

    subgraph Database["Database Layer"]
        DBInterface["Database Interface"]:::database
        DBTool["DB Management Tool"]:::database
        Schema["Schema Manager"]:::database
        Migration["Migration Handler"]:::database
        QueryOps["Query Operations"]:::database
        SMASH["Pool Metadata Service"]:::database

        click DBInterface "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db/src/Cardano/Db.hs"
        click DBTool "https://github.com/IntersectMBO/cardano-db-sync/blob/master/cardano-db-tool/src/Cardano/DbTool.hs"
        click Schema "https://github.com/IntersectMBO/cardano-db-sync/tree/master/schema/"
        click Migration "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db/src/Cardano/Db/Migration/"
        click QueryOps "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-db/src/Cardano/Db/Operations/"
        click SMASH "https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-smash-server/src/Cardano/SMASH/Server/"
    end

    Node --> Socket
    Socket --> ChainSync & StateQuery
    ChainSync & StateQuery --> DBSync
    DBSync --> Cache
    DBSync --> Rollback
    DBSync --> BlockProc & StateMan & TxProc
    BlockProc & StateMan & TxProc --> EraHandlers
    EraHandlers --> DBInterface
    DBInterface --> Schema
    DBInterface --> Migration
    DBInterface --> QueryOps
    DBInterface --> SMASH
    DBTool --> DB
    DBInterface --> DB
    DB --> Apps

    classDef external fill:#90EE90
    classDef storage fill:#FFA500
    classDef network fill:#ADD8E6
    classDef core fill:#0000FF,color:#FFFFFF
    classDef processing fill:#FFFF00
    classDef database fill:#FF8C00,color:#FFFFFF

    %% Legend
    subgraph Legend
        E[External Components]:::external
        S[Storage]:::storage
        N[Network Layer]:::network
        C[Core Components]:::core
        P[Processing]:::processing
        D[Database Components]:::database
    end
```
