# nathanwu8343/alphabet architecture

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

- Interactive diagram: https://gitdiagram.com/nathanwu8343/alphabet
- Repository: https://github.com/nathanwu8343/alphabet

## Overview

##### Project Type and Purpose
- This is a full-stack, microservices-style application built as a lightweight URL shortener. Its purpose is primarily to provide URL shortening functionality with a modern technology stack and advanced architectural patterns.
- The README mentions key architectural strategies such as DDD, CQRS, Clean Architecture, Unit of Work, and Repository Pattern, along with authentication/authorization and an API Gateway.

##### Main Components
- API Gateway: Represented by the ApiGateway project. This acts as the front door (using YARP) for routing requests and possibly handling Swagger-based API documentation and reverse proxying.
- Identity Server: The IdentityServer project handles Authentication and Authorization based on IdentityServer4. It will be a key external security component.
- URL Shortener Service: Composed of multiple layers:
- Presentation Layer: Found in the UrlShortener.Presentation project with controllers and API abstractions.
- Application Layer: Located in the UrlShortener.Application project, making use of CQRS handlers (commands, queries, events) via MediatR along with pipeline behaviors (e.g., logging, validation).
- Domain Layer: The UrlShortener.Domain project contains domain entities, domain events, value objects, and interfaces like repository abstractions.
- Infrastructure: The UrlShortener.Infrastructure project provides implementations for domain services such as caching (Redis), background jobs, and idempotence. It implements external integrations (for example, using ExternalContainerResource and ExternalHostResource) and has logic for short code generation.
- Persistence: The UrlShortener.Persistence project shows Entity Framework Core integration, including DbContexts (read and write), repositories, interceptors, and migration configurations along with handling the transactional outbox pattern.
- Shared Kernels and Contracts: These projects (e.g., SharedKernel, Contracts) provide common code and integration events used by several services.
- Service Defaults & Hosting: The Alphabet.AppHost and Alphabet.ServiceDefaults projects contain default configurations, extension methods, and hosting resources used across the system.

##### Relationships and Interactions
- Users/clients initiate requests that hit the API Gateway.
- The API Gateway routes traffic to the appropriate service, e.g. the URL Shortener API or Identity Server.
- The URL Shortener API processes commands and queries through the Application layer, interacting with the Domain for business rules via CQRS.
- The Application layer uses MediatR to delegate requests to the appropriate command/query handlers.
- Domain events trigger integration flows that are picked up by background jobs in the Infrastructure layer (via MassTransit and outbox patterns) and persist data through the Persistence layer.
- External dependencies (such as Redis for caching, MariaDB for data storage, and ELK for logging/monitoring) should be shown connected to the respective services.
- Shared kernel components and contracts indicate common definitions and messaging across services.

##### Architectural Patterns and Design Principles
- Use of DDD: Segregate domain concerns (entities, value objects, domain events) from application and infrastructure.
- CQRS: Clearly separate the read and write models in the Persistence layer, with dedicated query and command handlers in the Application layer.
- Clean Architecture: Maintain separation of concerns between Presentation, Application, Domain, Infrastructure, and Persistence.
- Use of Unit of Work and Repository Patterns: These are applied in the Persistence layer and service layers for data consistency.
- Authentication and Authorization responsibilities are clearly separated in the IdentityServer component.

##### Relevant Technologies and Frameworks
- ASP.NET Core 8.0 is the primary web framework.
- Entity Framework Core 8 is used for data access.
- MediatR is key for implementing CQRS.
- Yarp 2 in the API Gateway routes requests.
- IdentityServer4 provides auth security.
- Redis (and associated Redis services) handle caching.
- Other tools and libraries include Serilog, Swagger UI, FluentValidation, and ELK for observability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Clients"]:::client

    %% Core Microservices
    APIGateway["API Gateway - YARP"]:::gateway
    IdentityServer["Identity Server - IdentityServer4"]:::identity

    %% Shared Components
    SharedKernel["SharedKernel"]:::shared
    Contracts["Contracts"]:::shared

    %% Service Defaults & Hosting Components
    AppHost["Alphabet.AppHost"]:::hosting
    ServiceDefaults["Alphabet.ServiceDefaults"]:::hosting

    %% External Infrastructure
    Redis["Redis (Cache)"]:::external
    MariaDB["MariaDB (Data Storage)"]:::external
    ELK["ELK (Logging/Monitoring)"]:::external

    %% URL Shortener Service Subgraph
    subgraph "URL Shortener Service"
        direction TB
        US_Presentation["URL Shortener – Presentation Layer"]:::urlshortener
        US_Application["URL Shortener – Application Layer"]:::urlshortener
        US_Domain["URL Shortener – Domain Layer"]:::urlshortener
        US_Infrastructure["URL Shortener – Infrastructure Layer"]:::urlshortener
        US_Persistence["URL Shortener – Persistence Layer"]:::urlshortener
    end

    %% Data Flow
    Clients -->|"requests"| APIGateway
    APIGateway -->|"routes-auth"| IdentityServer
    APIGateway -->|"routes"| US_Presentation
    US_Presentation -->|"calls"| US_Application
    US_Application -->|"delegates-to"| US_Domain
    US_Domain -->|"triggers"| US_Infrastructure
    US_Infrastructure -->|"persists-to"| US_Persistence

    %% Infrastructure Integrations
    US_Infrastructure -->|"integrates-with"| Redis
    US_Infrastructure -->|"logs-to"| ELK
    US_Persistence -->|"stores-in"| MariaDB

    %% Shared Components Usage
    US_Application -->|"uses"| SharedKernel
    US_Domain -->|"uses"| Contracts

    %% Service Defaults & Hosting Usage
    APIGateway -->|"config"| AppHost
    APIGateway -->|"config"| ServiceDefaults
    IdentityServer -->|"config"| AppHost
    IdentityServer -->|"config"| ServiceDefaults

    %% Click Events for Components
    click APIGateway "https://github.com/nathanwu8343/alphabet/tree/master/src/ApiGateway"
    click IdentityServer "https://github.com/nathanwu8343/alphabet/tree/master/src/IdentityServer"
    click US_Presentation "https://github.com/nathanwu8343/alphabet/blob/master/src/UrlShortener.Presentation"
    click US_Application "https://github.com/nathanwu8343/alphabet/blob/master/src/UrlShortener.Application"
    click US_Domain "https://github.com/nathanwu8343/alphabet/blob/master/src/UrlShortener.Domain"
    click US_Infrastructure "https://github.com/nathanwu8343/alphabet/blob/master/src/UrlShortener.Infrastructure"
    click US_Persistence "https://github.com/nathanwu8343/alphabet/blob/master/src/UrlShortener.Persistence"
    click SharedKernel "https://github.com/nathanwu8343/alphabet/tree/master/src/SharedKernel"
    click Contracts "https://github.com/nathanwu8343/alphabet/tree/master/src/Contracts"
    click AppHost "https://github.com/nathanwu8343/alphabet/blob/master/src/Alphabet.AppHost"
    click ServiceDefaults "https://github.com/nathanwu8343/alphabet/blob/master/src/Alphabet.ServiceDefaults"

    %% Styles
    classDef client fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef gateway fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef identity fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef urlshortener fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef shared fill:#FFFF99,stroke:#333,stroke-width:2px;
    classDef hosting fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef external fill:#F5DEB3,stroke:#333,stroke-width:2px;
```
