# dimo-network/devices-api architecture

> Architecture diagram of the GitHub repository dimo-network/devices-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/devices-api
- Repository: https://github.com/dimo-network/devices-api

## Overview

##### Main System Components

a) API Layer:
- HTTP REST API (Swagger/OpenAPI documented)
- gRPC Services (aftermarket_devices and user_devices)
- WebHooks Controller

b) Core Services Layer:
- Device Management Services
- Integration Services (Tesla, Smartcar, AutoPi)
- NFT/Blockchain Services
- Event Services
- Authentication/Authorization Services

c) Data Storage:
- PostgreSQL Database (primary data store)
- Elasticsearch (device status and search)
- Redis (task queue)
- IPFS (document storage)

d) Message Brokers:
- Kafka (event streaming)
- NATS (real-time messaging)

##### Architectural Patterns to Emphasize

- Microservice Architecture: Show how this service fits into the broader DIMO ecosystem
- Event-Driven Architecture: Highlight Kafka producers/consumers
- Command Query Responsibility Segregation (CQRS): Separate read/write paths
- Repository Pattern: For data access abstraction

**┌─────────────────────────────────────────────────────────────┐**
- External Clients                         │
- (Mobile Apps, Web Apps, Other DIMO Services, Smart Devices) │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────────┐**
- API Gateway Layer                        │
- REST API (Swagger) │ gRPC Services │ Webhook Endpoints   │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────────┐**
- Service Layer                            │
- ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐   │
- Device    │  │ Integration  │  │      NFT/        │   │
- Services   │  │  Services    │  │ Blockchain Svcs  │   │
- ┘  └──────────────┘  └──────────────────┘   │
- ┘
- ↕
**┌─────────────────────────────────────────────────────────────┐**
- Infrastructure Layer                       │
- ┌─────────┐ ┌────────────┐ ┌───────┐ ┌───────┐ ┌────────┐  │
- Postgres │ │Elasticsearch│ │Redis  │ │Kafka  │ │ IPFS   │  │
- ┘ └────────────┘ └───────┘ └───────┘ └────────┘  │
- ┘

##### Important Flows to Highlight

- Device registration and management flow
- Integration authentication flow
- Event processing flow
- NFT minting and management flow
- Data ingestion and processing pipeline

##### Additional Elements

- Version/environment indicators
- Security boundaries
- Scalable components (marked by Kubernetes deployments)
- Monitoring points (ServiceMonitor templates)

##### Technical Details

- Kubernetes deployment boundaries
- Database migration paths
- API versioning
- Authentication flow with Dex
- Integration points with external services

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Layer
    subgraph Clients
        MA[Mobile Apps]
        WA[Web Apps]
        DS[DIMO Services]
        SD[Smart Devices]
    end

    %% API Gateway Layer
    subgraph API
        REST["REST API Controllers"]:::api
        GRPC["gRPC Services"]:::api
        WH["WebHooks Controller"]:::api
    end

    %% Service Layer
    subgraph Services
        DM["Device Management"]:::service
        DD["Device Definitions"]:::service
        UD["User Device Services"]:::service
        
        subgraph Integrations
            TS["Tesla Service"]:::integration
            SC["Smartcar Client"]:::integration
            AP["AutoPi Service"]:::integration
        end
        
        subgraph Blockchain
            NFT["NFT Services"]:::blockchain
            REG["Registry Services"]:::blockchain
        end
        
        ES["Event Services"]:::service
        AUTH["Authentication Services"]:::auth
        NATS["NATS Service"]:::messaging
    end

    %% Infrastructure Layer
    subgraph Infrastructure
        PG[(PostgreSQL)]:::database
        ELS[(Elasticsearch)]:::database
        RD[(Redis)]:::database
        KF[("Kafka")]:::messaging
        IPFS[("IPFS")]:::storage
    end

    %% Relationships
    Clients --> API
    API --> Services
    Services --> Infrastructure

    %% Click Events
    click REST "https://github.com/DIMO-Network/devices-api/tree/main/internal/controllers/"
    click GRPC "https://github.com/DIMO-Network/devices-api/tree/main/pkg/grpc/"
    click WH "https://github.com/DIMO-Network/devices-api/blob/main/internal/controllers/webhooks_controller.go"
    click DM "https://github.com/DIMO-Network/devices-api/blob/main/internal/controllers/devices_controller.go"
    click TS "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/tesla_service.go"
    click SC "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/smartcar_client.go"
    click AP "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/autopi_api_service.go"
    click NFT "https://github.com/DIMO-Network/devices-api/blob/main/internal/controllers/nft_controller.go"
    click REG "https://github.com/DIMO-Network/devices-api/tree/main/internal/services/registry/"
    click ES "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/event_service.go"
    click AUTH "https://github.com/DIMO-Network/devices-api/tree/main/internal/services/dex/"
    click ELS "https://github.com/DIMO-Network/devices-api/tree/main/internal/elasticsearch/"
    click IPFS "https://github.com/DIMO-Network/devices-api/tree/main/internal/services/ipfs/"
    click KF "https://github.com/DIMO-Network/devices-api/tree/main/internal/kafka/"
    click NATS "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/nats_service.go"
    click DD "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/device_definitions_service.go"
    click UD "https://github.com/DIMO-Network/devices-api/blob/main/internal/services/user_device_service.go"

    %% Styling
    classDef api fill:#2196F3,stroke:#fff,stroke-width:2px,color:#fff
    classDef service fill:#4CAF50,stroke:#fff,stroke-width:2px,color:#fff
    classDef integration fill:#FF9800,stroke:#fff,stroke-width:2px,color:#fff
    classDef blockchain fill:#9C27B0,stroke:#fff,stroke-width:2px,color:#fff
    classDef database fill:#FFC107,stroke:#fff,stroke-width:2px,color:#fff
    classDef messaging fill:#FF5722,stroke:#fff,stroke-width:2px,color:#fff
    classDef storage fill:#795548,stroke:#fff,stroke-width:2px,color:#fff
    classDef auth fill:#673AB7,stroke:#fff,stroke-width:2px,color:#fff
```
