# hcmc-metro-swd392/summer2025swd392_net1703_group2_be architecture

> Architecture diagram of the GitHub repository hcmc-metro-swd392/summer2025swd392_net1703_group2_be, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be
- Repository: https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be

## Overview

##### Project Type & Purpose
- This is a monolithic, layered ASP.NET Core Web API backend (“MetroTicketBE”) powering a metro ticketing system for Ho Chi Minh City.
- It implements end-to-end ticketing workflows (route search, purchase, QR check-in/out, over-station payment), staff/training scheduling, real-time notifications, and audit logging.

##### File Structure Analysis
- Top-level solution (.sln) with four projects:
- Domain – core entities, enums, DTOs
- Application – business services, SignalR hubs, AutoMapper mappings, third-party integrations (Redis, AWS, PayOS)
- Infrastructure – EF Core DbContext, repositories, UnitOf-Work, seeding
- WebAPI – controllers, DI extensions, program startup, SignalR endpoints, swagger/CORS/auth setup
- CI/CD pipeline under .github/workflows.
- External-integration code (Redis extensions, AWS S3/SES, PayOS).

##### README Insights
- Clean-layered architecture (Domain-Application-Infrastructure-WebAPI).
- Key capabilities: multi-line routing (StationGraph + Dijkstra), QR lifecycle (Redis short-lived + persisted for single rides), over-station price adjustments, SignalR notifications, JWT/Identity auth with Redis refresh tokens.
- Persistence: EF Core → PostgreSQL. Caching: Redis. Real-time: SignalR. Cloud: AWS S3/SES. Payments: PayOS.

##### Diagramming the Architecture
a. Main Components & Layers
- Clients (Web/Mobile) → HTTP/SignalR
- WebAPI Layer
– Controllers (REST endpoints)
– SignalR Hubs (real-time channels)
– Authentication & Authorization (JWT + Identity)
- Application Layer
– Services (IAuthService, ITicketService, ITrainScheduleService, etc.)
– Hubs (ChatRoomHub, LobbyHub, NotificationHub)
– Mappings (AutoMapper profiles)
– Integrations (Redis service, S3 service, Email service, PayOS service)
– StationGraph module (routing engine)
- Domain Layer
– Entities, Enums, DTOs
- Infrastructure Layer
– ApplicationDBContext (EF Core)
– Repositories & UnitOfWork
– Seeding logic
- External Systems
– PostgreSQL database
– Redis cache/session store
– AWS S3 & SES
– PayOS API
– CI/CD → GitHub Actions → AWS EC2/Kestrel

b. Relationships & Data Flow
1. Client issues REST call or opens SignalR connection against WebAPI.
2. WebAPI Controller dispatches to Application Services via DI.
3. Application Service executes business logic, may:
– Query StationGraph for routing,
– Generate/validate QR (persist or use Redis TTL),
– Trigger notifications via SignalR hub,
– Call Infrastructure Repositories to read/write Domain Entities,
– Upload attachments to S3 or send email via SES,
– Initiate payment link via PayOS SDK.
4. Infrastructure layer interacts with PostgreSQL and Redis.
5. Application returns DTOs to Controller → response to Client.

c. Architectural Patterns & Principles
- Layered/Clean architecture with clear separation of concerns
- Repository + Unit Of Work for data access
- Dependency Injection for service wiring
- Event-style notifications via SignalR
- External adapter pattern for AWS, Redis, PayOS
- Graph abstraction (StationGraph) encapsulates routing algorithm

d. Key Technologies
- ASP.NET Core 8, C#
- EF Core 8 (PostgreSQL via Npgsql)
- Redis (StackExchange.Redis)
- SignalR
- AWS S3 & SES
- PayOS SDK
- AutoMapper, Swagger (Swashbuckle)
- GitHub Actions → AWS EC2

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        direction TB
        WebClient["Web/Mobile Clients"]:::clients
    end

    subgraph "WebAPI Layer"
        direction TB
        Controllers["Controllers"]:::webapi
        SignalRTestController["SignalR Test Endpoint"]:::webapi
        DIExtensions["DI & Service Extensions"]:::webapi
        Program["Program (Startup)"]:::webapi
    end

    subgraph "Application Layer"
        direction TB
        IAuthService["IAuthService, ITicketService, ..."]:::app
        AuthService["AuthService, TicketService, ..."]:::app
        Hubs["SignalR Hubs (ChatRoomHub, LobbyHub)"]:::app
        NotificationHub["NotificationHub & UserId Providers"]:::app
        AutoMapper["AutoMapper Profiles"]:::app
        StationGraph["StationGraph Routing Engine"]:::app
        subgraph "External Integrations"
            direction TB
            RedisService["Redis Service"]:::app
            S3Service["S3 Service"]:::app
            EmailService["Email Service"]:::app
            PaymentService["PayOS Service"]:::app
        end
    end

    subgraph "Domain Layer"
        direction TB
        Entities["Entities, DTOs, Enums"]:::domain
    end

    subgraph "Infrastructure Layer"
        direction TB
        DbContext["ApplicationDBContext"]:::infra
        RepoInterfaces["Repository Interfaces"]:::infra
        RepoImpl["Repository Implementations & UnitOfWork"]:::infra
        Seeding["Seeding Logic"]:::infra
    end

    subgraph "External Systems"
        direction TB
        Postgres["PostgreSQL DB"]:::external
        RedisCache["Redis Cache"]:::external
        AWS_S3["AWS S3"]:::external
        AWS_SES["AWS SES"]:::external
        PayOS["PayOS API"]:::external
        CICD["CI/CD (GitHub Actions)"]:::external
        Hosting["AWS EC2 / Kestrel"]:::external
    end

    WebClient -->|HTTP/SignalR| Controllers
    Controllers -->|Calls Service Interfaces| IAuthService
    Controllers -->|Opens Hubs| Hubs
    Controllers -->|HTTP POST/GET| SignalRTestController
    Controllers -->|Uses DI Extensions| DIExtensions

    IAuthService --> AuthService
    AuthService --> StationGraph
    AuthService --> RedisService
    AuthService --> S3Service
    AuthService --> EmailService
    AuthService --> PaymentService
    AuthService -->|Queries/Writes| RepoInterfaces

    Hubs -->|Push Notifications| WebClient
    NotificationHub --> Hubs

    RepoInterfaces --> RepoImpl
    RepoImpl --> DbContext
    DbContext -->|SQL| Postgres
    DbContext --> Seeding

    RedisService -->|Redis GET/SET| RedisCache
    S3Service -->|AWS SDK| AWS_S3
    EmailService -->|AWS SDK| AWS_SES
    PaymentService -->|SDK Calls| PayOS

    CICD -->|Deploy| Hosting

    click Controllers "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.WebAPI/Controllers"
    click SignalRTestController "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.WebAPI/Controllers/SignalRTestController.cs"
    click DIExtensions "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.WebAPI/Extentions"
    click Program "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.WebAPI/Program.cs"
    click CICD "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/.github/workflows/backend-cicd.yml"

    click IAuthService "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.Application/IService"
    click AuthService "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.Application/Service"
    click Hubs "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.Application/Hub"
    click NotificationHub "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/SignalR/NotificationHub.cs"
    click AutoMapper "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/Mappings/AutoMappingProfile.cs"
    click StationGraph "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/Service/StationGraph.cs"
    click RedisService "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/IService/IRedisService.cs"
    click S3Service "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/IService/IS3Service.cs"
    click EmailService "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/IService/IEmailService.cs"
    click PaymentService "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Application/IService/IPaymentService.cs"

    click Entities "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Domain"
    click DbContext "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Infrastructure/Context/ApplicationDBContext.cs"
    click RepoInterfaces "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.Infrastructure/IRepository"
    click RepoImpl "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/tree/main/MetroTicketBE.Infrastructure/Repository"
    click Seeding "https://github.com/hcmc-metro-swd392/summer2025swd392_net1703_group2_be/blob/main/MetroTicketBE.Infrastructure/Seeding/ApplicationDBContextSeed.cs"

    classDef clients fill:#D0E6F5,stroke:#333,stroke-width:1px
    classDef webapi fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef app fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef domain fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef infra fill:#FFF9C4,stroke:#333,stroke-width:1px
    classDef external fill:#BBDEFB,stroke:#333,stroke-width:1px
```
