# bluesky-social/indigo architecture

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

- Interactive diagram: https://gitdiagram.com/bluesky-social/indigo
- Repository: https://github.com/bluesky-social/indigo

## Overview

##### High-Level Architecture Components

The system should be divided into these main components:

a) Core Services:
- BigSky (BGS) - Graph service
- Palomar - Full-text search service
- Hepa - Auto-moderation service

b) Core Libraries:
- API Packages (atproto, bsky)
- Identity Management
- Cryptographic Operations
- Repository Management
- Protocol Syntax
- Data Structures (MST)

##### Component Relationships

**[External Clients/Apps] <---> [API Layer (XRPC)]**
- ↓
**[Core Services Layer]**
- BigSky (Social Graph)
- Palomar (Search)
- Hepa (Moderation)
- ↓
**[Core Libraries Layer]**
- Identity (DID/Handle Resolution)
- Crypto (Signing/Keys)
- Repo (Data Storage)
- MST (Merkle Search Tree)
- Syntax (Protocol Parsing)
- ↓
**[Storage/Infrastructure Layer]**
- Redis
- Database
- Event System

##### Detailed Component Breakdown

For each major service:

BigSky (BGS):
- Connections to repo management
- Event processing system
- Social graph data flow
- Integration with identity services

Palomar:
- Search indexing flow
- Query processing
- Integration with storage
- Full-text search components

Hepa:
- Moderation rules engine
- Event processing
- Integration with Ozone
- Auto-moderation flow

##### Cross-Cutting Concerns

Aspects across all components:
- Metrics/Monitoring
- Authentication/Authorization
- Event Processing
- Caching Layers

##### Data Flow Indicators

Show:
- API request/response paths
- Event propagation
- Data persistence flows
- Authentication flows

##### Integration Points

Highlight:
- External API endpoints
- Inter-service communication
- Storage interfaces
- Event bus connections

##### Specific Implementation Details

Include:
- XRPC client/server communication
- DID resolution flow
- Repository management
- Cryptographic operations flow

Remember to emphasize the modular nature of the system and how components can be deployed independently while maintaining protocol compatibility.

This architecture represents a distributed system implementing the AT Protocol, focusing on scalability, security, and maintainability while enabling social networking features through a decentralized approach.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "External Layer"
        Client["External Clients/Apps"]:::external
    end

    subgraph "API Layer"
        XRPC["XRPC Server"]:::api
        click XRPC "https://github.com/bluesky-social/indigo/blob/main/xrpc/xrpc.go"
    end

    subgraph "Core Services"
        BGS["BigSky (BGS)\nGraph Service"]:::service
        click BGS "https://github.com/bluesky-social/indigo/tree/main/cmd/bigsky"
        Palomar["Palomar\nSearch Service"]:::service
        click Palomar "https://github.com/bluesky-social/indigo/tree/main/cmd/palomar"
        Hepa["Hepa\nAuto-moderation"]:::service
        click Hepa "https://github.com/bluesky-social/indigo/tree/main/cmd/hepa"
    end

    subgraph "Core Libraries"
        API["API Packages\n(atproto, bsky)"]:::library
        click API "https://github.com/bluesky-social/indigo/tree/main/api/atproto"
        Identity["Identity\nManagement"]:::library
        click Identity "https://github.com/bluesky-social/indigo/tree/main/atproto/identity"
        Crypto["Cryptographic\nOperations"]:::security
        click Crypto "https://github.com/bluesky-social/indigo/tree/main/atproto/crypto"
        Repo["Repository\nManagement"]:::library
        click Repo "https://github.com/bluesky-social/indigo/blob/main/repo/repo.go"
        MST["Data Structures\n(MST)"]:::library
        click MST "https://github.com/bluesky-social/indigo/blob/main/mst/mst.go"
        Syntax["Protocol\nSyntax"]:::library
        click Syntax "https://github.com/bluesky-social/indigo/tree/main/atproto/syntax"
        Lexicon["Lexicon\nProtocol Definition"]:::library
        click Lexicon "https://github.com/bluesky-social/indigo/tree/main/atproto/lexicon"
    end

    subgraph "Infrastructure Layer"
        Redis["Redis\nCache"]:::storage
        DB["Database"]:::storage
        Events["Event System"]:::infrastructure
        click Events "https://github.com/bluesky-social/indigo/blob/main/events/events.go"
        CarStore["Car Store"]:::storage
        click CarStore "https://github.com/bluesky-social/indigo/tree/main/carstore"
    end

    %% Connections
    Client --> XRPC
    XRPC --> BGS & Palomar & Hepa
    
    BGS --> API
    BGS --> Events
    BGS --> Repo
    
    Palomar --> Events
    Palomar --> Repo
    
    Hepa --> Events
    Hepa --> Repo
    
    API --> Identity
    API --> Crypto
    API --> Syntax
    API --> Lexicon
    
    Repo --> MST
    Repo --> CarStore
    
    Events --> Redis
    Events --> DB
    
    Identity --> DB
    
    %% Styling
    classDef external fill:#f9f,stroke:#333,stroke-width:2px
    classDef api fill:#9cf,stroke:#333,stroke-width:2px
    classDef service fill:#6495ED,stroke:#333,stroke-width:2px
    classDef library fill:#90EE90,stroke:#333,stroke-width:2px
    classDef security fill:#ff6b6b,stroke:#333,stroke-width:2px
    classDef storage fill:#d3d3d3,stroke:#333,stroke-width:2px
    classDef infrastructure fill:#FFE4B5,stroke:#333,stroke-width:2px
```
