# litestar-org/advanced-alchemy architecture

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

- Interactive diagram: https://gitdiagram.com/litestar-org/advanced-alchemy
- Repository: https://github.com/litestar-org/advanced-alchemy

## Overview

##### Main Components

a) Core Components:
- Repository Layer
- Service Layer
- Database Abstraction Layer
- Type System
- Configuration Management
- Framework Integration Layer

b) Framework Integrations:
- Litestar Integration
- FastAPI Integration
- Starlette Integration
- Sanic Integration

**┌─ Web Framework Layer ─────────────────────────────┐**
- Litestar | FastAPI | Starlette | Sanic           │
- Framework Integration Layer ────────────────────┬─┘
- Extensions Module                               │
- Service Layer ─────────────────────────────────┤
- Sync/Async Services                            │
- Repository Layer ──────────────────────────────┤
- Sync/Async Repositories                        │
- Database Abstraction Layer ────────────────────┤
- SQLAlchemy Integration                         │
- ┘

##### Component Relationships

- Web frameworks → Framework Integration Layer
- Framework Integration Layer → Service Layer
- Service Layer → Repository Layer
- Repository Layer → Database Abstraction Layer

##### Key Features to Highlight

- Sync/Async support
- Bulk operations
- Database dialect support
- Alembic integration
- Type system features
- Mixins and utilities

##### Implementation Details

- Clear separation between sync and async implementations
- Database backend support (SQLite, Postgres, MySQL, Oracle, etc.)
- Integration points for different frameworks
- Configuration flow
- Repository pattern implementation
- Service layer abstraction

##### Additional Elements

- Component types
- Integration points

##### Notes for the Engineer

- Keep the main flow clear by focusing on the core layers
- How the repository and service patterns are implemented
- Flexibility of framework integration
- Demonstrate the separation of concerns
- Database transaction handling
- How the type system integrates

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Framework Layer"
        Litestar["Litestar"]:::framework
        FastAPI["FastAPI"]:::framework
        Flask["Flask"]:::framework
        Sanic["Sanic"]:::framework
        Starlette["Starlette"]:::framework
    end

    subgraph "Integration Layer"
        LitestarInt["Litestar Integration"]:::integration
        click LitestarInt "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/extensions/litestar/"
        FlaskInt["Flask Integration"]:::integration
        click FlaskInt "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/extensions/flask/"
        SanicInt["Sanic Integration"]:::integration
        click SanicInt "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/extensions/sanic.py"
        StarletteInt["Starlette Integration"]:::integration
        click StarletteInt "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/extensions/starlette.py"
    end

    subgraph "Service Layer"
        AsyncService["SQLAlchemy Async Service"]:::service
        click AsyncService "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/service/_async.py"
        SyncService["SQLAlchemy Sync Service"]:::service
        click SyncService "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/service/_sync.py"
    end

    subgraph "Repository Layer"
        AsyncRepo["SQLAlchemy Async Repository"]:::repository
        click AsyncRepo "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/repository/_async.py"
        SyncRepo["SQLAlchemy Sync Repository"]:::repository
        click SyncRepo "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/repository/_sync.py"
    end

    subgraph "Model Layer"
        BaseModels["Base Models"]:::model
        click BaseModels "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/base.py"
        Mixins["Mixins"]:::model
        click Mixins "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/mixins"
        Types["Types"]:::model
        click Types "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/types"
    end

    subgraph "Configuration Layer"
        Config["Configuration System"]:::config
        click Config "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/config"
        AlembicInt["Alembic Integration"]:::config
        click AlembicInt "https://github.com/litestar-org/advanced-alchemy/tree/main/advanced_alchemy/alembic"
        CLI["CLI Tools"]:::config
        click CLI "https://github.com/litestar-org/advanced-alchemy/blob/main/advanced_alchemy/cli.py"
    end

    subgraph "Database Layer"
        SQLite[(SQLite)]:::database
        PostgreSQL[(PostgreSQL)]:::database
        MySQL[(MySQL)]:::database
        Oracle[(Oracle)]:::database
        Spanner[(Google Spanner)]:::database
        DuckDB[(DuckDB)]:::database
        MSSQL[(MS SQL Server)]:::database
        CockroachDB[(CockroachDB)]:::database
    end

    %% Framework to Integration Connections
    Litestar --> LitestarInt
    FastAPI --> StarletteInt
    Flask --> FlaskInt
    Sanic --> SanicInt
    Starlette --> StarletteInt

    %% Integration to Service Connections
    LitestarInt --> AsyncService & SyncService
    FlaskInt --> SyncService
    SanicInt --> AsyncService
    StarletteInt --> AsyncService

    %% Service to Repository Connections
    AsyncService --> AsyncRepo
    SyncService --> SyncRepo

    %% Repository to Model Connections
    AsyncRepo & SyncRepo --> BaseModels
    AsyncRepo & SyncRepo --> Mixins
    AsyncRepo & SyncRepo --> Types

    %% Configuration Connections
    Config --> AsyncRepo & SyncRepo
    Config --> AsyncService & SyncService
    AlembicInt --> BaseModels
    CLI --> AlembicInt

    %% Database Connections
    AsyncRepo --> SQLite & PostgreSQL & MySQL & Oracle & Spanner & DuckDB & MSSQL & CockroachDB
    SyncRepo --> SQLite & PostgreSQL & MySQL & Oracle & Spanner & DuckDB & MSSQL & CockroachDB

    %% Styling
    classDef framework fill:#b3e0ff,stroke:#333,stroke-width:2px
    classDef integration fill:#99ccff,stroke:#333,stroke-width:2px
    classDef service fill:#99ff99,stroke:#333,stroke-width:2px
    classDef repository fill:#b3ffb3,stroke:#333,stroke-width:2px
    classDef model fill:#ffcc99,stroke:#333,stroke-width:2px
    classDef config fill:#e6e6e6,stroke:#333,stroke-width:2px
    classDef database fill:#ffb366,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        Framework["Framework"]:::framework
        Integration["Integration"]:::integration
        Service["Service"]:::service
        Repository["Repository"]:::repository
        Model["Model"]:::model
        Configuration["Configuration"]:::config
        Database[("Database")]:::database
    end
```
