# azure/azurite architecture

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

- Interactive diagram: https://gitdiagram.com/azure/azurite
- Repository: https://github.com/azure/azurite

## Overview

##### Project Type and Purpose
- This is “Azurite,” a stand-alone emulator for Azure Storage services (Blob, Queue, Table).
- Written in TypeScript, it exposes HTTP endpoints that mimic Azure Storage REST APIs for local development and testing.
- Core components: a CLI (and VS Code extension), three service emulators (Blob, Queue, Table), shared common libraries, multiple persistence providers (in-memory, file system, Loki, SQL), and generated request/response middleware from Swagger specs.

##### File Structure Analysis
- Top-level scripts & config: Dockerfile(s), azure-pipelines.yml, GitHub actions, ESLint/Prettier, `package.json`, build scripts under `scripts/`.
- Source code (`src/`):
- `extension.ts` & `main.ts`: VS Code extension and top-level entrypoint.
- `azurite.ts`: main CLI bootstrap.
- `blob/`, `queue/`, `table/`: each service’s implementation subdivided into:
– **Configuration & Environment** (`*Configuration.ts`, `*Environment.ts`)
– **Server & Factory** (`*Server.ts`, `*ServerFactory.ts`)
– **Authentication** (SAS, SharedKey, Token, public access)
– **Middlewares** (authentication, CORS/Preflight, context injection, telemetry, strict-model)
– **Generated** (Express adapters, handlers, middleware from Swagger)
– **Handlers** (business logic by operation type)
– **Persistence** (metadata stores and extent stores with QueryInterpreter)
– **GC** (garbage-collection managers)
- Shared code (`src/common/`): interfaces (ILogger, IDataStore, IEnvironment), base classes (ServerBase, ConfigurationBase), persistence abstractions, telemetry, logging strategies, VSC server manager state machines, utility streams, mutex, zero-byte stream.
- Persistence implementations: in-memory, file-system, Loki.js, SQL (via SqlBlob… and SqlExtent… stores).
- Tests covering all layers under `tests/`.
- Swagger definitions under `swagger/` drive code generation.

##### Architectural Patterns & Design Principles
- Micro-services style: three separate Express apps (Blob, Queue, Table), each on its own port.
- Factory pattern to instantiate servers with pluggable environment/configuration/persistence.
- Middleware pipeline for cross-cutting concerns (auth, CORS, telemetry, context).
- Strategy pattern for persistence and authentication methods.
- Generated code from OpenAPI/Swagger ensuring contract adherence.
- Dependency injection via environment interfaces.
- CQRS-like separation: request parsing → business handler → data store interaction → response serialization.

##### Components and Interactions
- CLI / VS Code Extension
- Parses command-line args or VS Code commands → chooses in-memory or disk/SQL persistence → invokes ServerFactories.
- ServerFactories (BlobServerFactory, QueueServerFactory, TableServerFactory)
- Build Express apps: mount generated routes & middleware → register custom middlewares & handlers → start listening.
- Express Middleware Pipeline (per service)
1. CORS/Preflight (PreflightMiddlewareFactory)
2. Authentication (shared-key, SAS, token; authenticator implementations)
3. Context injection (BlobStorageContext / QueueStorageContext / TableStorageContext)
4. Strict model validation (enforce request schema)
5. Telemetry logging
6. Generated deserializer → dispatch → handler middleware → serializer → error handling
- Handlers
- Invoke service-specific logic: blob upload/download, queue enqueue/dequeue, table CRUD & query.
- Persistence Layer
- ExtentStore (holds raw data chunks) + MetadataStore (keeps metadata & indexing)
- QueryInterpreter for Table & Blob/Queue query filters
- GCManager cleans expired blobs/messages
- Common Utilities
- Logger & Telemetry (Winston, VSC strategies)
- Mutex, streams, configuration base classes
- External Services / Tools
- Node.js, Express.js, Swagger codegen, Loki.js, SQLite/MySQL drivers (for SQL stores)

- Clear component boundaries and labels
- Notes or callouts for key architectural patterns (Factory, Strategy, Middleware pipeline, Codegen).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Layer
    subgraph "Entry Layer"
        CLI["Azurite CLI"]:::service
        VSCodeExt["VS Code Extension"]:::service
        Main["CLI Main Bootstrap"]:::service
    end
    CLI -->|"invokes"| Main
    VSCodeExt -->|"invokes"| Main

    %% Service Layer
    subgraph "Blob Service" 
        direction TB
        BF["BlobServerFactory"]:::service
        BS["BlobServer (Express App)"]:::service
        BF --> BS
        BS --> BM1["CORS/Preflight"]:::middleware
        BS --> BM2["Authentication"]:::middleware
        BS --> BM3["Context Injection"]:::middleware
        BS --> BM4["Strict Model Validation"]:::middleware
        BS --> BM5["Telemetry Logging"]:::middleware
        BS --> BM6["Swagger Generated Pipeline"]:::middleware
        BM6 --> BH["Handlers"]:::service
        BH --> BP["Persistence Layer"]:::persistence
        BP -->|"uses"| BPE["ExtentStore / MetadataStore"]:::persistence
        BP -->|"uses"| BPQ["QueryInterpreter"]:::persistence
        BH --> BG["BlobGCManager"]:::service
    end

    subgraph "Queue Service"
        direction TB
        QF["QueueRequestListenerFactory"]:::service
        QS["QueueServer (Express App)"]:::service
        QF --> QS
        QS --> QM1["CORS/Preflight"]:::middleware
        QS --> QM2["Authentication"]:::middleware
        QS --> QM3["Context Injection"]:::middleware
        QS --> QM4["Strict Model Validation"]:::middleware
        QS --> QM5["Telemetry Logging"]:::middleware
        QS --> QM6["Swagger Generated Pipeline"]:::middleware
        QM6 --> QH["Handlers"]:::service
        QH --> QP["Persistence Layer"]:::persistence
        QP -->|"uses"| QPE["ExtentStore / MetadataStore"]:::persistence
        QP -->|"uses"| QPQ["QueryInterpreter"]:::persistence
        QH --> QG["QueueGCManager"]:::service
    end

    subgraph "Table Service"
        direction TB
        TF["TableRequestListenerFactory"]:::service
        TS["TableServer (Express App)"]:::service
        TF --> TS
        TS --> TM1["CORS/Preflight"]:::middleware
        TS --> TM2["Authentication"]:::middleware
        TS --> TM3["Context Injection"]:::middleware
        TS --> TM4["Strict Model Validation"]:::middleware
        TS --> TM5["Telemetry Logging"]:::middleware
        TS --> TM6["Swagger Generated Pipeline"]:::middleware
        TM6 --> TH["Handlers"]:::service
        TH --> TP["Persistence Layer"]:::persistence
        TP -->|"uses"| TPE["MetadataStore"]:::persistence
        TP -->|"uses"| TPQ["QueryInterpreter"]:::persistence
        TH --> TB["TableBatchOrchestrator"]:::service
    end

    %% Common Services
    subgraph "Common Services" 
        direction TB
        ConfigBase["ConfigurationBase"]:::common
        ServerBase["ServerBase"]:::common
        EnvBase["Environment"]:::common
        PersistenceAbs["Persistence Abstractions"]:::common
        Logger["Logger & Telemetry"]:::common
        Utils["Utility Modules"]:::common
    end

    %% Arrows from Entry to Services
    Main --> BF
    Main --> QF
    Main --> TF

    %% Styling
    classDef service fill:#D0E8FF,stroke:#0274B3,stroke-width:1px
    classDef middleware fill:#FFE5B4,stroke:#FF8C00,stroke-width:1px
    classDef persistence fill:#DFFFD6,stroke:#228B22,stroke-width:1px
    classDef common fill:#F0F0F0,stroke:#A9A9A9,stroke-width:1px

    %% Click Events
    click CLI "https://github.com/azure/azurite/blob/main/src/azurite.ts"
    click VSCodeExt "https://github.com/azure/azurite/blob/main/src/extension.ts"
    click Main "https://github.com/azure/azurite/blob/main/src/main.ts"
    click BF "https://github.com/azure/azurite/blob/main/src/blob/BlobServerFactory.ts"
    click BS "https://github.com/azure/azurite/blob/main/src/blob/BlobServer.ts"
    click BPE "https://github.com/azure/azurite/tree/main/src/blob/persistence/"
    click BG "https://github.com/azure/azurite/blob/main/src/blob/gc/BlobGCManager.ts"
    click QF "https://github.com/azure/azurite/blob/main/src/queue/QueueRequestListenerFactory.ts"
    click QS "https://github.com/azure/azurite/blob/main/src/queue/QueueServer.ts"
    click QPE "https://github.com/azure/azurite/tree/main/src/queue/persistence/"
    click QG "https://github.com/azure/azurite/blob/main/src/queue/gc/QueueGCManager.ts"
    click TF "https://github.com/azure/azurite/blob/main/src/table/TableRequestListenerFactory.ts"
    click TS "https://github.com/azure/azurite/blob/main/src/table/TableServer.ts"
    click TPE "https://github.com/azure/azurite/tree/main/src/table/persistence/"
    click TB "https://github.com/azure/azurite/blob/main/src/table/batch/TableBatchOrchestrator.ts"
    click ConfigBase "https://github.com/azure/azurite/blob/main/src/common/ConfigurationBase.ts"
    click ServerBase "https://github.com/azure/azurite/blob/main/src/common/ServerBase.ts"
    click EnvBase "https://github.com/azure/azurite/blob/main/src/common/Environment.ts"
    click PersistenceAbs "https://github.com/azure/azurite/tree/main/src/common/persistence/"
    click Logger "https://github.com/azure/azurite/blob/main/src/common/Logger.ts"
    click Utils "https://github.com/azure/azurite/tree/main/src/common/utils/"
```
