# djamalovaziz/basic_backend architecture

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

- Interactive diagram: https://gitdiagram.com/djamalovaziz/basic_backend
- Repository: https://github.com/djamalovaziz/basic_backend

## Overview

##### Project type and purpose
- This is a modular Rust-based backend service following a layered (hexagonal/ports-and-adapters) architecture.
- It provides interchangeable interfaces (HTTP: Actix/Axum, CLI, gRPC via Tonic), pluggable database backends (SurrealDB, PostgreSQL), and encapsulates business rules in domain/services layers.

##### File structure
- Top‐level crates:
- common: shared types, constants, errors, utility functions, response models
- domain: core business models, DTOs, repository interfaces, domain service traits
- services: concrete business logic implementations and permission checks
- databases: two adapter crates (_surrealdb, postgresql) implementing repository interfaces, schema migrations, connection pooling
- interface: four separate adapter crates (_actix_web, _axum, _clap, _tonic) exposing APIs to clients
- container: dependency-injection/wiring code that ties together interfaces, services, domains, and repositories
- core: the main binary entry point that invokes the container to spin up the selected interface
- Support files:
- config/: configuration templates
- .env, rustfmt.toml, GitHub Actions for CI/CD
- media/: static assets (avatars)

##### Extract insights from the README
- Version history shows iterative backend development: user/organization/branch relations, permission optimizations, cascading operations, PostgreSQL support in progress.

a. Main components:
- Clients (External callers): REST clients, CLI users, gRPC clients
- Interface Adapters: ActixWeb, Axum, Clap (CLI), Tonic (gRPC)
- Application Layer: container + core (orchestrator)
- Domain Layer: domain models, DTOs, repository trait definitions, service trait definitions
- Service Implementations: business-logic + permission modules (services crate)
- Persistence Adapters: SurrealDB adapter, PostgreSQL adapter (databases/* crates)
- Common Utilities: shared types, errors, constants (common crate)
- Configuration: config files, environment settings
- Infrastructure: Docker container definitions, CI/CD workflows

b. Relationships & data flows:
1. Client → Interface Adapter: incoming HTTP/CLI/gRPC request
2. Interface Adapter → Container/Core: invokes wiring to resolve concrete services & repositories
3. Core → Domain/Service: application layer passes call to domain service trait
4. Domain Service → Repository Interface: service logic calls repository trait methods
5. Repository Interface → Persistence Adapter: concrete adapter (SurrealDB or PostgreSQL) handles actual DB calls
6. Persistence Adapter → Database: runs queries/migrations
7. Domain Service → Interface Adapter: returns domain DTOs or common response types
8. Interface Adapter → Client: serializes & responds

c. Architectural patterns & principles:
- Hexagonal (Ports & Adapters): domain at center, with input/output ports (traits) and adapters (interface crates, database crates)
- Dependency Injection: container crate binds traits to implementations
- Separation of Concerns: interface vs. domain vs. persistence vs. common utilities
- Pluggability: swap HTTP frameworks or database backends by configuring the container

d. Key technologies & libraries:
- Rust edition, Cargo workspaces
- Web frameworks: Actix-Web, Axum
- CLI: Clap
- gRPC: Tonic
- Databases: SurrealDB driver, SQLx/PostgreSQL driver
- Dependency injection: custom container crate
- Config management: .env, basic.config

##### Detailed capturing of essential elements
- Common crate as a utility overlay accessible by all layers.
- Config/env injection into container.
- Migration files under each database adapter to show schema evolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    REST["REST Clients"]:::external
    CLIU["CLI Users"]:::external
    GRPC["gRPC Clients"]:::external

    %% Configuration & Utilities
    CONFIG["Configuration (.env, basic.config)"]:::infra
    COMMON["Common Utilities"]:::utility

    %% Interface Layer
    subgraph "Interface Layer"
        ACTIX["Actix-Web Adapter"]:::interface
        AXUM["Axum Adapter"]:::interface
        CLAP["Clap CLI Adapter"]:::interface
        TONIC["Tonic gRPC Adapter"]:::interface
    end

    %% Application Layer
    subgraph "Application Layer"
        CONTAINER["Dependency Injection Container"]:::app
        CORE["Core (main binary)"]:::app
    end

    %% Domain & Services Layer
    subgraph "Domain & Services Layer"
        DOMAIN["Domain Traits & Models"]:::domain
        SERVICES["Service Implementations"]:::domain
    end

    %% Persistence Adapters Layer
    subgraph "Persistence Adapters"
        SURR_ADAPT["SurrealDB Adapter"]:::persistence
        PG_ADAPT["PostgreSQL Adapter"]:::persistence
    end

    %% Databases
    subgraph "Databases"
        SURR_DB["SurrealDB"]:::external
        PG_DB["PostgreSQL"]:::external
    end

    %% Flows
    REST -->|"HTTP Request"| ACTIX
    REST -->|"HTTP Request"| AXUM
    CLIU -->|"CLI Command"| CLAP
    GRPC -->|"gRPC Call"| TONIC

    ACTIX -->|"invoke()"| CONTAINER
    AXUM -->|"invoke()"| CONTAINER
    CLAP -->|"invoke()"| CONTAINER
    TONIC -->|"invoke()"| CONTAINER

    CONFIG -->|"load()"| CONTAINER
    COMMON --> CONTAINER

    CONTAINER -->|"resolve UserService"| CORE
    CORE -->|"UserService.create_user()"| SERVICES
    SERVICES -->|"calls Repo.find_by_id()"| DOMAIN
    DOMAIN -->|"UserRepo.save()"| SURR_ADAPT
    DOMAIN -->|"UserRepo.save()"| PG_ADAPT

    SURR_ADAPT -->|"SQL/Surql Queries"| SURR_DB
    PG_ADAPT -->|"SQL Queries"| PG_DB

    SURR_ADAPT --> COMMON
    PG_ADAPT --> COMMON
    SERVICES --> COMMON

    SURR_ADAPT -->|"migration files"| SURR_ADAPT
    PG_ADAPT -->|"migration files"| PG_ADAPT

    CORE --> ACTIX
    CORE --> AXUM
    CORE --> CLAP
    CORE --> TONIC

    %% Click Events
    click COMMON "https://github.com/djamalovaziz/basic_backend/tree/main/common/"
    click DOMAIN "https://github.com/djamalovaziz/basic_backend/tree/main/domain/"
    click SERVICES "https://github.com/djamalovaziz/basic_backend/tree/main/services/"
    click SURR_ADAPT "https://github.com/djamalovaziz/basic_backend/tree/main/databases/_surrealdb/"
    click SurrealSchemas "https://github.com/djamalovaziz/basic_backend/tree/main/databases/_surrealdb/schemas/"
    click SurrealPool "https://github.com/djamalovaziz/basic_backend/blob/main/databases/_surrealdb/src/pool.rs"
    click SurrealDAO "https://github.com/djamalovaziz/basic_backend/tree/main/databases/_surrealdb/src/dao/"
    click PG_ADAPT "https://github.com/djamalovaziz/basic_backend/tree/main/databases/postgresql/"
    click PGMigrations "https://github.com/djamalovaziz/basic_backend/tree/main/databases/postgresql/sql/"
    click PGPool "https://github.com/djamalovaziz/basic_backend/blob/main/databases/postgresql/src/pool.rs"
    click PGDAO "https://github.com/djamalovaziz/basic_backend/tree/main/databases/postgresql/src/dao/"
    click ACTIX "https://github.com/djamalovaziz/basic_backend/tree/main/interface/_actix_web/"
    click AXUM "https://github.com/djamalovaziz/basic_backend/tree/main/interface/_axum/"
    click CLAP "https://github.com/djamalovaziz/basic_backend/tree/main/interface/_clap/"
    click TONIC "https://github.com/djamalovaziz/basic_backend/tree/main/interface/_tonic/"
    click CONTAINER "https://github.com/djamalovaziz/basic_backend/blob/main/container/src/lib.rs"
    click CORE "https://github.com/djamalovaziz/basic_backend/blob/main/core/src/main.rs"
    click CONFIG "https://github.com/djamalovaziz/basic_backend/blob/main/config/basic.config"

    %% Styles
    classDef external fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef interface fill:#daf0fd,stroke:#42a1c7,stroke-width:1px;
    classDef app fill:#d4f5d4,stroke:#3aa63f,stroke-width:1px;
    classDef domain fill:#fff3b0,stroke:#e1ad01,stroke-width:1px;
    classDef persistence fill:#ffd8a8,stroke:#ff8c00,stroke-width:1px;
    classDef infra fill:#eeeeee,stroke:#999,stroke-width:1px;
    classDef utility fill:#f0f0f0,stroke:#666,stroke-width:1px;
```
