How djamalovaziz/basic_backend works
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.