# dimo-network/identity-api architecture

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

- Interactive diagram: https://gitdiagram.com/dimo-network/identity-api
- Repository: https://github.com/dimo-network/identity-api

## Overview

##### Main Components

a. API Layer
- GraphQL API Server (evident from /graph directory)
- Schema Definitions (found in /graph/schema/*.graphqls)
- Resolvers (various *.resolvers.go files)

b. Core Services Layer
- Contract Event Services (/internal/services)
- Staking Services (/internal/services/staking)
- Tableland API Service
- Data Loaders (/internal/loader)

c. Repository Layer
- Vehicle Repository
- Aftermarket Repository
- DCN Repository
- Manufacturer Repository
- Stake Repository
- Synthetic Device Repository
- Developer License Repository
- Privileges Repository

d. Database Layer
- PostgreSQL Database (evident from migrations and sqlboiler.toml)

e. External Integrations
- Blockchain Contracts (from /internal/contracts)
- Tableland Integration

##### Component Relationships

- Client Requests → GraphQL API
- GraphQL API → Data Loaders → Repositories
- Repositories → PostgreSQL Database
- Contract Events Consumer → Blockchain
- Services → Tableland API
- Services → Repositories

##### Architectural Patterns to Highlight

- GraphQL-first architecture
- Repository pattern implementation
- Event-driven architecture for blockchain events
- Data loader pattern for N+1 query prevention

**[Client Layer]**
- ↓
**[GraphQL API Layer]**
- ↓
**[Data Loader Layer]**
- ↓
**[Services Layer]**
- ↓
**[Repository Layer]**
- ↓
**[Database Layer]**

**[External Systems]**
- Blockchain ←→ Contract Events Consumer
- Tableland API ←→ Services Layer

Important Details to Include:

##### Configuration Management
- Settings.yaml configuration flow
- Environment variables handling

##### Infrastructure Components
- Kubernetes deployment elements (from /charts directory)
- Monitoring setup (ServiceMonitor)

##### Data Flow Patterns
- Vehicle-centric data model
- Privilege and access control flows
- Device pairing relationships

This architecture represents a modern GraphQL API system with blockchain integration, following clean architecture principles with clear separation of concerns between layers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Client
        CL[Client Requests]
    end

    subgraph API
        GQL[GraphQL API Server]:::api
        Schema[Schema Definitions]:::api
        Resolvers[Resolvers]:::api
    end

    subgraph Services
        DL[Data Loaders]:::service
        CES[Contract Event Services]:::service
        SS[Staking Services]:::service
        TAS[Tableland API Service]:::service
    end

    subgraph Repositories
        VR[Vehicle Repository]:::repo
        AR[Aftermarket Repository]:::repo
        DR[DCN Repository]:::repo
        MR[Manufacturer Repository]:::repo
        SR[Stake Repository]:::repo
        SDR[Synthetic Device Repository]:::repo
        DLR[Developer License Repository]:::repo
        PR[Privileges Repository]:::repo
    end

    subgraph Database
        PG[(PostgreSQL)]:::db
        Migrations[Database Migrations]:::db
        Models[Database Models]:::db
    end

    subgraph External
        BC[Blockchain Contracts]:::external
        TL[Tableland API]:::external
    end

    subgraph Infrastructure
        CM[Configuration Management]:::infra
        KD[Kubernetes Deployment]:::infra
        MS[Monitoring Setup]:::infra
    end

    %% Relationships
    CL --> GQL
    GQL --> Schema
    GQL --> Resolvers
    GQL --> DL
    DL --> VR & AR & DR & MR & SR & SDR & DLR & PR
    CES --> BC
    SS --> SR
    TAS --> TL
    VR & AR & DR & MR & SR & SDR & DLR & PR --> PG
    PG --> Migrations
    PG --> Models
    CM --> GQL

    %% Click Events
    click GQL "https://github.com/DIMO-Network/identity-api/tree/main/graph"
    click Schema "https://github.com/DIMO-Network/identity-api/tree/main/graph/schema"
    click Resolvers "https://github.com/DIMO-Network/identity-api/blob/main/graph/*.resolvers.go"
    click CES "https://github.com/DIMO-Network/identity-api/blob/main/internal/services/contracts_events_consumer.go"
    click SS "https://github.com/DIMO-Network/identity-api/tree/main/internal/services/staking"
    click TAS "https://github.com/DIMO-Network/identity-api/blob/main/internal/services/tableland_api_service.go"
    click DL "https://github.com/DIMO-Network/identity-api/tree/main/internal/loader"
    click VR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/vehicle"
    click AR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/aftermarket"
    click DR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/dcn"
    click MR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/manufacturer"
    click SR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/stake"
    click SDR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/synthetic"
    click DLR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/developerlicense"
    click PR "https://github.com/DIMO-Network/identity-api/tree/main/internal/repositories/vehicleprivilege"
    click Migrations "https://github.com/DIMO-Network/identity-api/tree/main/migrations"
    click Models "https://github.com/DIMO-Network/identity-api/tree/main/models"
    click BC "https://github.com/DIMO-Network/identity-api/tree/main/internal/contracts"
    click CM "https://github.com/DIMO-Network/identity-api/blob/main/internal/config/settings.go"
    click KD "https://github.com/DIMO-Network/identity-api/tree/main/charts/identity-api"
    click MS "https://github.com/DIMO-Network/identity-api/blob/main/charts/identity-api/templates/servicemonitor.yaml"

    %% Styles
    classDef api fill:#2196F3,stroke:#1565C0,color:white
    classDef service fill:#4CAF50,stroke:#2E7D32,color:white
    classDef repo fill:#FFC107,stroke:#FFA000,color:black
    classDef db fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef external fill:#F44336,stroke:#C62828,color:white
    classDef infra fill:#607D8B,stroke:#455A64,color:white
```
