# jason810496/dcard-advertisement-api architecture

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

- Interactive diagram: https://gitdiagram.com/jason810496/dcard-advertisement-api
- Repository: https://github.com/jason810496/dcard-advertisement-api

## Overview

##### Overall Project Type and Purpose
- That this is a back‑end API service dedicated to advertisement creation and query.
- Read-heavy nature, with performance targets (e.g., 1000 RPS at minimum, with design enhancements to hit 10,000 RPS) and the use of caching tiers to ensure low-latency response times.
- That additional deployment and CI/CD aspects (Docker, Kubernetes deployments, Terraform infra, GitHub Actions workflows) support the overall operation.

##### Main Components
a. Ingress / API Gateway:
– Mark an “Ingress” component that represents the external entry point (load balancer or gateway).

b. Stateless Application Servers (AP Cluster):
– Represent multiple API server instances (e.g., AP1, AP2, AP3) in a “Stateless AP Cluster” that handle public and admin API calls.
– Inside each API server block, indicate the local in-memory cache, which is refreshed by background goroutines. You might also show that one or more processes incorporate extra “BG Goroutines” for local cache refresh.

c. Caches:
– Represent the “Local Cache” on each API instance (illustrating the use of fastcache or gin-cache for caching by URI).

d. Database Tier:
– Show a “Postgres Primary” and a “Postgres Replica” (or a cluster block with a line denoting WAL replication) for persistent storage of advertisement data.

e. Background / Scheduling Components:
– Include a “Corn Job” (or Scheduler) component that periodically enumerates hotspot parameter combinations and updates both the Redis cache and local cache.
– Optionally, show the “Generator” component (from cmd/generator) if it is used to pre-populate or refresh data.

f. CI/CD and Deployment/Infra:

##### Relationships and Data Flow
– (1) When the request is “cache hit”: the API consults the local cache and/or Redis.
– (2) When the local or Redis cache is “missed”: the API falls back to querying the Postgres database (primary or replica).
- That advertisement creation (admin API) directs writes into the Postgres primary, while read queries come from both caches and replicas.

##### Architectural Patterns and Technologies
- That the system is built with Golang.
- Mention the use of caching strategies (e.g., “Cache by URI” via gin-cache, multi-layer cache pre-heating using Lua scripts for atomic updates).
- Use labels or callouts to show that the architecture was designed to avoid cache avalanche scenarios by pre-computing hot combinations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingress / API Gateway
    Ingress["Ingress (API Gateway)"]:::ingress

    %% Stateless AP Cluster
    subgraph "Stateless AP Cluster"
        direction TB
        API["API Server"]:::api
        Router["API Routing & Handlers"]:::api
        Admin["Admin Handler"]:::api
        Public["Public Handler"]:::api
        LocalCache["Local In‑Memory Cache"]:::localcache
        BGGoroutine["BG Goroutine"]:::bggroup

        API --> LocalCache
        API --> BGGoroutine
        API --> Router
        Router --> Admin
        Router --> Public
    end

    %% Caches
    subgraph "Caching Layers"
        direction TB
        Redis["Redis Cache (Sentinel optional)"]:::redis
        Lua["Lua Scripts for Pre‑heating"]:::redis
    end

    %% Database Tier
    subgraph "Database Tier"
        direction TB
        PGPrimary["Postgres DB (Primary)"]:::database
        PGReplica["Postgres DB (Replica)"]:::database
        PGPrimary -->|"replicates"| PGReplica
    end

    %% Background / Scheduling Components
    subgraph "Background & Scheduling"
        direction TB
        Scheduler["Scheduler / Corn Job"]:::scheduler
        SchedulerLogic["Scheduler Logic (HotData & LocalCache)"]:::scheduler
    end

    %% Generator Component
    Generator["Generator Service"]:::generator

    %% CI/CD and Deployment/Infra
    CICD["CI/CD & Deployment/Infra"]:::cicd

    %% Data Flow
    Ingress -->|"API Request"| API

    %% Cache hit flows
    API -->|"cacheHit"| LocalCache
    API -->|"cacheHit"| Redis

    %% Cache miss and write flows
    API -->|"cacheMiss"| PGReplica
    API -->|"writes"| PGPrimary

    %% Pre‐heating and synchronization flows
    Scheduler -.->|"preheat"| Redis
    Scheduler -.->|"refresh"| LocalCache
    BGGoroutine -.->|"syncRefresh"| LocalCache
    Lua -->|"update"| Redis

    %% Generator flows
    Generator -->|"pre‑populate"| PGPrimary
    Generator -->|"pre‑populate"| Redis

    %% CI/CD does not participate in runtime flow, shown for infra context
    CICD --- Ingress
    CICD --- API
    CICD --- Redis
    CICD --- PGPrimary

    %% Click Events
    click Ingress "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/kubernetes/api/service.yaml"
    click Ingress "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/gke/api/service.yaml"
    click API "https://github.com/jason810496/dcard-advertisement-api/blob/main/cmd/api/main.go"
    click Router "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/handlers/router.go"
    click Admin "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/handlers/admin.go"
    click Public "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/handlers/public.go"
    click LocalCache "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/cache/local.go"
    click Redis "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/gke/redis/service.yaml"
    click Redis "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/kubernetes/redis/service.yaml"
    click Lua "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/cache/lua.go"
    click PGPrimary "https://github.com/jason810496/dcard-advertisement-api/blob/main/docker-compose-pg-primary-replica.yaml"
    click PGReplica "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/database/connection.go"
    click Scheduler "https://github.com/jason810496/dcard-advertisement-api/blob/main/cmd/scheduler/main.go"
    click SchedulerLogic "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/scheduler/hotdata.go"
    click SchedulerLogic "https://github.com/jason810496/dcard-advertisement-api/blob/main/pkg/scheduler/localCache.go"
    click Generator "https://github.com/jason810496/dcard-advertisement-api/blob/main/cmd/generator/main.go"
    click Generator "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/gke/generator/pod.yaml"
    click Generator "https://github.com/jason810496/dcard-advertisement-api/blob/main/deployments/kubernetes/generator/pod.yaml"
    click CICD "https://github.com/jason810496/dcard-advertisement-api/tree/main/.github/workflows/"
    click CICD "https://github.com/jason810496/dcard-advertisement-api/tree/main/infra/"

    %% Styles
    classDef ingress fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef api fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef localcache fill:#D6EAF8,stroke:#1F618D,stroke-width:2px;
    classDef bggroup fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef redis fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef database fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef scheduler fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef generator fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef cicd fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
```
