# crystal-bank/crystalbank architecture

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

- Interactive diagram: https://gitdiagram.com/crystal-bank/crystalbank
- Repository: https://github.com/crystal-bank/crystalbank

## Overview

##### Main Components Identification

a. Core Domains:
- Accounts Domain
- Customers Domain
- Users Domain
- API Keys Domain
- Transactions Domain (with sub-domains)

b. Infrastructure Components:
- PostgreSQL EventStore
- API Server
- Authentication Layer
- Event Bus
- Projections System

##### Architectural Patterns to Highlight

The system implements several important patterns that should be represented:

a. CQRS (Command Query Responsibility Segregation):
- Commands (write operations)
- Queries (read operations)
- Event Sourcing
- Projections

b. REST API Architecture:
- OpenAPI/Swagger Integration
- JWT Authentication
- API Key Management

**┌─ Client Layer ─────────────────────────────┐**
- REST API Clients                           │
- ┘
- ↕ HTTP/REST
**┌─ API Layer ──────────────────────────────────┐**
- Authentication | Authorization | API Gateway  │
- ┘
- ↕
**┌─ Domain Layer ────────────────────────────────────────────────┐**
- ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌────────────────────┐  │
- Accounts │ │Customers │ │Users    │ │Transactions        │  │
- Commands │ │Commands  │ │Commands │ │┌─────────────────┐ │  │
- Events   │ │Events    │ │Events   │ ││Internal Transfer│ │  │
- Queries  │ │Queries   │ │Queries  │ ││Postings         │ │  │
- ┘ └──────────┘ └─────────┘ └─────────────────┘ │  │
- ┘  │
- ┘
- ↕
**┌─ Infrastructure Layer ──────────────────────────────────────┐**
- EventStore (PostgreSQL) | Event Bus | Projections Store     │
- ┘

##### Important Relationships

- Event flow between domains
- Command/Query separation
- API authentication flow
- Projection updates
- Domain interaction patterns

##### Additional Details

Annotations for:
- API endpoints (/accounts, /customers, etc.)
- Event types (AccountOpened, TransferInitiated, etc.)
- Authentication flow
- Currency support
- Customer types (business, individual)

##### Implementation Notes

- Event-driven architecture
- Domain isolation
- Clear boundaries between write and read operations
- Security layers
- Data flow directions

This system design should reflect the event-sourced, domain-driven nature of the application while clearly showing how the different components interact to provide banking functionality.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        REST[REST API Clients]:::client
    end

    subgraph API
        API_GW["API Gateway"]:::api
        click API_GW "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/server/openapi.cr"
        AUTH["Authentication Layer"]:::security
        click AUTH "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/shared/api/authorization.cr"
        JWT["JWT Auth"]:::security
        click JWT "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/shared/api/jwt.cr"
        AC["Access Control"]:::security
        click AC "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/shared/services/access_control.cr"
    end

    subgraph Domains
        subgraph Accounts
            ACC_CMD["Commands"]:::command
            ACC_EVT["Events"]:::event
            ACC_QRY["Queries"]:::query
            click Accounts "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/accounts/"
        end

        subgraph Customers
            CUST_CMD["Commands"]:::command
            CUST_EVT["Events"]:::event
            CUST_QRY["Queries"]:::query
            click Customers "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/customers/"
        end

        subgraph Users
            USR_CMD["Commands"]:::command
            USR_EVT["Events"]:::event
            USR_QRY["Queries"]:::query
            click Users "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/users/"
        end

        subgraph Transactions
            TRANS_CMD["Commands"]:::command
            TRANS_EVT["Events"]:::event
            TRANS_QRY["Queries"]:::query
            INT_TRANS["Internal Transfers"]:::domain
            POST["Postings"]:::domain
            click Transactions "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/transactions/"
            click INT_TRANS "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/transactions/internal_transfers/"
            click POST "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/transactions/postings/"
        end

        subgraph APIKeys
            KEY_CMD["Commands"]:::command
            KEY_EVT["Events"]:::event
            KEY_QRY["Queries"]:::query
            click APIKeys "https://github.com/Crystal-Bank/crystalbank/tree/master/app/src/domains/api_keys/"
        end
    end

    subgraph Infrastructure
        EVTSTORE[("Event Store")]:::database
        click EVTSTORE "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/config/initializers/eventstore.cr"
        EVTBUS["Event Bus"]:::infra
        click EVTBUS "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/config/initializers/event_bus.cr"
        PROJ["Projections System"]:::infra
        click PROJ "https://github.com/Crystal-Bank/crystalbank/blob/master/app/src/config/initializers/projections.cr"
    end

    %% Relationships
    REST --> API_GW
    API_GW --> AUTH
    AUTH --> JWT
    AUTH --> AC

    %% Domain interactions
    AUTH --> Accounts
    AUTH --> Customers
    AUTH --> Users
    AUTH --> Transactions
    AUTH --> APIKeys

    %% Event flow
    ACC_CMD --> EVTBUS
    CUST_CMD --> EVTBUS
    USR_CMD --> EVTBUS
    TRANS_CMD --> EVTBUS
    KEY_CMD --> EVTBUS

    EVTBUS --> EVTSTORE
    EVTSTORE --> PROJ
    PROJ --> ACC_QRY
    PROJ --> CUST_QRY
    PROJ --> USR_QRY
    PROJ --> TRANS_QRY
    PROJ --> KEY_QRY

    %% Styling
    classDef client fill:#f9f,stroke:#333
    classDef api fill:#69f,stroke:#333
    classDef security fill:#f66,stroke:#333
    classDef command fill:#9f9,stroke:#333
    classDef event fill:#ff9,stroke:#333
    classDef query fill:#f9f,stroke:#333
    classDef domain fill:#6f9,stroke:#333
    classDef database fill:#fc9,stroke:#333
    classDef infra fill:#ccc,stroke:#333
```
