# diogocunhacardoso/coinllector-api-express-ts architecture

> Architecture diagram of the GitHub repository diogocunhacardoso/coinllector-api-express-ts, 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/diogocunhacardoso/coinllector-api-express-ts
- Repository: https://github.com/diogocunhacardoso/coinllector-api-express-ts

## Overview

##### Project Type and Purpose
- This is a monolithic, TypeScript-based REST API backend (“full-stack” on the server side) for an application that lets users collect and manage European coin faces.
- It exposes HTTP endpoints (Express), persists data in MongoDB (via Mongoose), handles authentication/authorization (JWT, sessions, cookies, RBAC), processes images via Cloudinary, and uses Redis for rate limiting or session caching.

##### High-Level File Structure & Architectural Patterns
- Entry point: src/app.ts / src/routes.ts
- Layered architecture:
- Middleware (authentication, error handling, validation, rate limiting)
- Routing (src/routes/*.route.ts)
- Controllers (src/controller/*.controller.ts)
- Services / business logic (src/service/*.service.ts)
- Models / persistence (src/models/*.model.ts using Mongoose)
- Schema/validation (Zod schemas in src/schema)
- Utils & constants (logging, JWT, email, cloudinary client, etc.)
- Supplemental components: Cron jobs (in utils or separate scheduler module), Swagger docs, Prometheus metrics endpoint, tests.

##### Key Components
a. External Clients and Entry Points
- User’s browser or mobile app (REST/HTTPS)
- Swagger UI (docs endpoint)
b. API Layer (running in Docker container / Node.js runtime)
- Load Balancer or API Gateway (if present; optional)
- Express Server
- Middleware Pipeline (CORS, Helmet, JSON parser, rate limiter, deserializeUser)
- Route Handlers → Controllers
- Controllers invoke Services
- Services invoke Models / Utilities
c. Persistence & Cache
- MongoDB cluster (collections: users, sessions, coins, countries, verification codes)
- Redis instance (rate limiter, session cache)
d. External Services
- Cloudinary (image upload, manipulation)
- Email SMTP service (via nodemailer)
- Google OAuth provider (for social login flow)
- Prometheus (scrapes metrics endpoint)
e. Auxiliary Components
- Cron scheduler (cleanup jobs for inactive/unverified accounts)
- Logger (Pino) writing to stdout / files
- Swagger docs served from /swagger

##### Architectural Patterns & Design Principles
- Layered separation: each layer has its own responsibility.
- Single-responsibility services (one service per entity: coin, country, session, user)
- Middleware chain for cross-cutting concerns (error handling, validation, auth).
- Use of cron/scheduled tasks to handle background jobs.
- Externalize configuration via environment variables (.env).
- Observability via Prometheus metrics and structured logs.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        Browser["Browser / Mobile App"]:::clients
        SwaggerUI["Swagger UI"]:::clients
    end

    %% API Server
    subgraph "API Server (Docker / Node.js)" 
        direction TB
        Express["Express Server"]:::apiServer

        subgraph "Middleware Pipeline"
            direction TB
            AsyncErr["asyncErrorWrapper"]:::apiServer
            DeserUser["deserializeUser"]:::apiServer
            ErrorHandler["errorHandler"]:::apiServer
            MulterMW["multer"]:::apiServer
            ReqPerm["requirePermission"]:::apiServer
            ReqUser["requireUser"]:::apiServer
            ValidateRes["validateResource"]:::apiServer
        end

        subgraph "Routing"
            direction TB
            AuthRoute["auth.route"]:::apiServer
            CoinRoute["coin.route"]:::apiServer
            CountryRoute["country.route"]:::apiServer
            SessionRoute["session.route"]:::apiServer
            UserRoute["user.route"]:::apiServer
        end

        subgraph "Controllers"
            direction TB
            AuthCtrl["auth.controller"]:::apiServer
            CoinCtrl["coin.controller"]:::apiServer
            CountryCtrl["country.controller"]:::apiServer
            SessionCtrl["session.controller"]:::apiServer
            UserCtrl["user.controller"]:::apiServer
            IndexCtrl["index.controller"]:::apiServer
        end

        subgraph "Services"
            direction TB
            AuthSvc["auth.service"]:::apiServer
            CoinSvc["coin.service"]:::apiServer
            CountrySvc["country.service"]:::apiServer
            SessionSvc["session.service"]:::apiServer
            UserSvc["user.service"]:::apiServer
        end

        subgraph "Data Access (Models)"
            direction TB
            CoinModel["coin.model"]:::apiServer
            CountryModel["country.model"]:::apiServer
            SessionModel["session.model"]:::apiServer
            UserModel["user.model"]:::apiServer
            VerifCodeModel["verificationCode.model"]:::apiServer
        end

        subgraph "Utilities & Config"
            direction TB
            JWTUtils["jwt.utils"]:::apiServer
            CookieUtil["cookies/createCookie"]:::apiServer
            DBConn["dbConnect"]:::apiServer
            CloudUtil["cloudinary"]:::apiServer
            Mailer["mailer/emailTemplate"]:::apiServer
            RateLimiter["ratelimiter"]:::apiServer
            Logger["logger"]:::apiServer
            SwaggerUtil["swagger"]:::apiServer
            ServerHelpers["server/appError/appAssert"]:::apiServer
            EnvConsts["env/appErrorCode/imageRules/permissions/time"]:::apiServer
        end

        Cron["Cron Scheduler"]:::scheduler
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB[(MongoDB Cluster)]:::datastore
        Redis[(Redis Cache)]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        CloudinaryExt["Cloudinary"]:::external
        SMTP["Email SMTP"]:::external
        GoogleOAuth["Google OAuth"]:::external
    end

    %% Observability
    Prometheus["Prometheus"]:::external

    %% Connections
    Browser -->|"HTTPS REST"| Express
    SwaggerUI -->|"Docs UI"| Express

    Express -->|"passes through"| AsyncErr
    AsyncErr --> DeserUser --> ValidateRes --> ReqUser --> ReqPerm --> MulterMW --> ErrorHandler
    ErrorHandler --> AuthRoute
    ErrorHandler --> CoinRoute
    ErrorHandler --> CountryRoute
    ErrorHandler --> SessionRoute
    ErrorHandler --> UserRoute

    AuthRoute --> AuthCtrl
    CoinRoute --> CoinCtrl
    CountryRoute --> CountryCtrl
    SessionRoute --> SessionCtrl
    UserRoute --> UserCtrl

    AuthCtrl --> AuthSvc
    CoinCtrl --> CoinSvc
    CountryCtrl --> CountrySvc
    SessionCtrl --> SessionSvc
    UserCtrl --> UserSvc
    IndexCtrl --> AuthSvc

    AuthSvc --> UserModel
    AuthSvc --> SessionModel
    CoinSvc --> CoinModel
    CountrySvc --> CountryModel
    SessionSvc --> SessionModel
    UserSvc --> UserModel
    AuthSvc --> VerifCodeModel

    AuthSvc --> Redis
    SessionSvc --> Redis

    CoinSvc --> CloudinaryExt
    AuthSvc --> SMTP
    AuthSvc --> GoogleOAuth

    CoinModel --> MongoDB
    CountryModel --> MongoDB
    SessionModel --> MongoDB
    UserModel --> MongoDB
    VerifCodeModel --> MongoDB

    Express -->|"metrics endpoint"| Prometheus

    Cron --> AuthSvc
    Cron --> UserSvc
    Cron --> SessionSvc

    %% Click Events
    click Express "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/app.ts"
    click AuthRoute "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/routes/auth.route.ts"
    click CoinRoute "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/routes/coin.route.ts"
    click CountryRoute "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/routes/country.route.ts"
    click SessionRoute "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/routes/session.route.ts"
    click UserRoute "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/routes/user.route.ts"
    click AsyncErr "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/asyncErrorWrapper.ts"
    click DeserUser "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/deserializeUser.middleware.ts"
    click ErrorHandler "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/errorHandler.ts"
    click MulterMW "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/multer.ts"
    click ReqPerm "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/requirePermission.ts"
    click ReqUser "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/requireUser.middleware.ts"
    click ValidateRes "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/middleware/validateResource.middleware.ts"
    click AuthCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/auth.controller.ts"
    click CoinCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/coin.controller.ts"
    click CountryCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/country.controller.ts"
    click SessionCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/session.controller.ts"
    click UserCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/user.controller.ts"
    click IndexCtrl "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/controller/index.ts"
    click AuthSvc "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/service/auth.service.ts"
    click CoinSvc "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/service/coin.service.ts"
    click CountrySvc "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/service/country.service.ts"
    click SessionSvc "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/service/session.service.ts"
    click UserSvc "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/service/user.service.ts"
    click CoinModel "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/models/coin.model.ts"
    click CountryModel "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/models/country.model.ts"
    click SessionModel "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/models/session.model.ts"
    click UserModel "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/models/user.model.ts"
    click VerifCodeModel "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/models/verificationCode.model.ts"
    click JWTUtils "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/jwt.utils.ts"
    click CookieUtil "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/createCookie.ts"
    click DBConn "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/dbConnect.ts"
    click CloudUtil "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/cloudinary.ts"
    click Mailer "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/mailer.ts"
    click RateLimiter "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/ratelimiter.ts"
    click Logger "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/logger.ts"
    click SwaggerUtil "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/swagger.ts"
    click EnvConsts "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/constants/env.ts"
    click ServerHelpers "https://github.com/diogocunhacardoso/coinllector-api-express-ts/blob/main/src/utils/appError.ts"

    %% Styles
    classDef clients fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef apiServer fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef datastore fill:#98FB98,stroke:#333,stroke-width:1px
    classDef datastores fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#FFDEAD,stroke:#333,stroke-width:1px
    classDef scheduler fill:#F0E68C,stroke:#333,stroke-width:1px
```
