# amansrivstv/discount-service-unifize architecture

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

- Interactive diagram: https://gitdiagram.com/amansrivstv/discount-service-unifize
- Repository: https://github.com/amansrivstv/discount-service-unifize

## Overview

##### Project type and purpose
- This is a single-service, full-stack microservice (backend-only) implementing a discount engine.
- It exposes HTTP endpoints via FastAPI for calculating discounts and validating voucher codes.
- It uses SQLite (SQLAlchemy) for persistence, Pydantic for schema validation, a custom TTL cache, and pytest for testing.

##### File structure
- Top-level: config and orchestration files (Dockerfile, Makefile), source under `app/`, tests under `tests/`.
- `app/main.py` – entry point, defines FastAPI app, startup/shutdown lifecycles (runs DB migrations/seeding).
- `app/api/` – API layer (routes + Pydantic schemas).
- `app/services/` – business logic (the DiscountService).
- `app/db/` – data layer (SQLAlchemy Base, models, seeding logic).
- `app/core/` – cross-cutting concerns (config, errors, TTL cache).
- `app/fake_data.py` – seed-data definitions.
- `tests/` – integration/unit tests using in-memory SQLite.

##### README for additional insights
- Describes the lifecycle: startup seeds DB, error handling, caching strategy.
- Lists the discount-calculation sequence and caching details.

##### Main components
a. Client (UI or any HTTP consumer)
b. FastAPI Application
- Router/Controller (`routes.py`)
- Schemas (Pydantic models for request/response)
- Lifecycle manager (startup seeding)
c. Service Layer
- `DiscountService` with methods `calculate_cart_discounts` and `validate_discount_code`
d. Core Utilities
- TTL Cache (in-memory with 5-minute TTL)
- Configuration loader (`Settings`)
- Error translator (maps domain errors to HTTP responses)
e. Data Layer
- SQLAlchemy Engine & Session
- Models (BrandDiscount, CategoryDiscount, BankOffer, Voucher)
- Seed module (loads `fake_data.py` at startup)
f. SQLite Database (file or in-memory)
g. External build/deploy artifacts
- Docker container
- Makefile targets

##### Relationships and interactions
- Client sends HTTP request → FastAPI route handler
- Handler invokes DiscountService
- DiscountService queries TTL Cache for discount maps, voucher, bank offers
- On cache miss, it fetches from DB via SQLAlchemy Session, populates the cache
- Service applies sequential discount logic: brand → category → voucher → bank offer
- Service returns a DiscountedPrice DTO
- FastAPI handler wraps in HTTP 200 or maps service errors to HTTP 400
- On startup, FastAPI app uses a lifespan context to:
- Create tables (via `seed.create_tables`)
- Seed initial data

##### Architectural patterns and design principles
- Layered architecture: API → Service → Data
- Single Responsibility: separate modules for schema, routing, business logic, data models, seeding, caching
- Dependency injection via FastAPI (session, settings)
- TTL caching to reduce DB hits
- Centralized error handling

##### Elements
- Clear labels (e.g., “FastAPI Router”, “DiscountService”, “TTL Cache”, “SQLite DB”)
- Rectangles for services/modules
- Parallelogram or cloud for external client
- Optional: annotate the Docker container boundary and configuration source (env vars → Settings)

##### Final recommendations
- Be very detailed: break down the service into controllers, service methods, cache operations, and data access.
- Startup sequence and normal request sequence separately or in a combined flow.
- Keep component labels consistent with package/module names in the file tree.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["HTTP Client"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB

        %% API Layer
        subgraph "API Layer"
            direction TB
            Entry["FastAPI App\n(app/main.py)"]:::entry
            Router["FastAPI Router\n(app/api/routes.py)"]:::api
            Schemas["Pydantic Schemas\n(app/api/schemas.py)"]:::api
        end

        %% Service and Core Layer
        subgraph "Service & Core"
            direction TB
            DiscountService["DiscountService\n(app/services/discount_service.py)"]:::service
            TTLCache["TTL Cache\n(app/core/cache.py)"]:::cache
            Config["Settings\n(app/core/config.py)"]:::core
            Errors["Error Translator\n(app/core/errors.py)"]:::core
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            Base["SQLAlchemy Base & Session\n(app/db/base.py)"]:::db
            Models["ORM Models\n(app/db/models.py)"]:::db
            Seed["Seed Logic\n(app/db/seed.py)"]:::db
            FakeData["Seed Data Definitions\n(app/fake_data.py)"]:::db
        end

        %% Database
        DB["SQLite Database"]:::dbCylinder
    end

    %% Orchestration Files
    DockerfileDef["Dockerfile"]:::infra
    MakefileDef["Makefile"]:::infra

    %% Request Flow
    Client -->|"HTTP Request"| Router
    Router -->|"Invokes"| DiscountService
    DiscountService -->|"Read/Write"| TTLCache
    TTLCache -->|"Cache Miss Queries"| Base
    Base -->|"Model Mapping"| Models
    Base -->|"SQL Queries"| DB
    DiscountService -->|"Uses Config & Errors"| Config
    DiscountService --> Config
    DiscountService --> Errors
    Entry -->|"Startup Lifecycle"| Seed
    Seed -->|"Loads Data From"| FakeData
    Seed --> Base
    Base --> DB

    %% Orchestration Links
    DockerfileDef --- DockerfileDef
    MakefileDef --- MakefileDef

    %% Click Events
    click Entry "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/main.py"
    click Router "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/api/routes.py"
    click Schemas "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/api/schemas.py"
    click DiscountService "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/services/discount_service.py"
    click TTLCache "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/core/cache.py"
    click Config "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/core/config.py"
    click Errors "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/core/errors.py"
    click Base "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/db/base.py"
    click Models "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/db/models.py"
    click Seed "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/db/seed.py"
    click FakeData "https://github.com/amansrivstv/discount-service-unifize/blob/main/app/fake_data.py"
    click DockerfileDef "https://github.com/amansrivstv/discount-service-unifize/tree/main/Dockerfile"
    click MakefileDef "https://github.com/amansrivstv/discount-service-unifize/tree/main/Makefile"

    %% Styles
    classDef external fill:#f8f,stroke:#333,stroke-width:1px;
    classDef api fill:#bbdefb,stroke:#2196f3,stroke-width:1px;
    classDef entry fill:#bbdefb,stroke:#1976d2,stroke-width:1px;
    classDef service fill:#90caf9,stroke:#1565c0,stroke-width:1px;
    classDef core fill:#c5cae9,stroke:#3f51b5,stroke-width:1px;
    classDef cache fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px;
    classDef db fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
    classDef dbCylinder fill:#a5d6a7,stroke:#2e7d32,stroke-width:1px,shape:cylinder;
    classDef infra fill:#eeeeee,stroke:#757575,stroke-width:1px;
```
