# poleeast/pinpin_backend architecture

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

- Interactive diagram: https://gitdiagram.com/poleeast/pinpin_backend
- Repository: https://github.com/poleeast/pinpin_backend

## Overview

##### Project Type and Purpose
- Type: Backend REST API server built with NestJS (Node.js + TypeScript).
- Purpose: CRUD and business logic around users, user profiles, categories, travel-interest data, with JWT-based authentication and file uploads via Cloudinary.
- Key features:
– Modular controllers/services/repositories
– JWT auth (guard + strategy)
– TypeORM entities & custom repositories
– External Cloudinary integration

##### Main Architectural Layers
a. Presentation Layer
– Controllers (HTTP endpoints)
– Global filters & interceptors for error handling and standardized API responses
b. Application Layer
– Services (business logic) in each module (user, userProfile, category, cloudinary)
c. Domain/Infrastructure Layer
– Entities (TypeORM)
– Repositories (custom TypeORM repositories)
– Database (SQL)
– External services (Cloudinary)

##### Primary Components
1. Client(s)
– Mobile/Web clients invoking HTTP endpoints
2. API Gateway / NestJS HTTP Server
– Main entrypoint (src/main.ts → app.module)
– global_exception.filter, api_responses.decorator
3. Authentication Subsystem
– jwt.strategy.ts
– jwt.guard.ts
– user module (login/signup)
4. Modules
– UserModule (controllers, services, repos, entities)
– UserProfileModule
– CategoryModule
– CloudinaryModule
5. Database
– SQL database (tables based on entities in src/entities)
– db預設資料.sql seed data
6. External Service
– Cloudinary (image uploads)

##### Relationships and Data Flow
- Client → HTTP Request → NestJS Controller
- Controller → Service (injects repositories)
- Service → Repository → Database
- Service → External (Cloudinary)
- Auth Flow:
– Client sends JWT in header → jwt.guard → jwt.strategy validates → request.user populated
- Response: Service returns DTO → Controller returns HTTP response (with api_responses decorator)

##### Architectural Patterns & Principles
- Layered Architecture (Controller → Service → Repository → DB)
- Dependency Injection (Nest providers in modules)
- Modularization (each domain in its own module folder)
- Single Responsibility (separate decorator, filter, guard, util classes)
- Repository Pattern (custom TypeORM repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef client fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef nestjs fill:#blue,stroke:#333,stroke-width:1px,color:#fff;
    classDef data fill:#a2f5a2,stroke:#333,stroke-width:1px;
    classDef cross fill:#f5b442,stroke:#333,stroke-width:1px;
    classDef ext fill:#cda4e5,stroke:#333,stroke-width:1px;

    Client["Client"]:::client

    subgraph "API Gateway / NestJS HTTP Server"
        direction TB
        Main["main.ts"]:::nestjs
        AppMod["app.module.ts"]:::nestjs
    end

    subgraph "Cross-cutting"
        direction TB
        Filter["global_exception.filter.ts"]:::cross
        Decorator["api_responses.decorator.ts"]:::cross
    end

    subgraph "Authentication Subsystem"
        direction TB
        Guard["jwt.guard.ts"]:::cross
        Strategy["jwt.strategy.ts"]:::cross
        JwtInterface["jwt.interface.ts"]:::cross
    end

    subgraph "User Module"
        direction TB
        UCtrl["user.controller.ts"]:::nestjs
        UService["user.service.ts"]:::nestjs
        URepo["user.repository.ts"]:::data
        UEntity["user.entity.ts"]:::data
        UDTO["user.dto.ts"]:::data
    end

    subgraph "UserProfile Module"
        direction TB
        UPctrl["userProfile.controller.ts"]:::nestjs
        UPsvc["userProfile.service.ts"]:::nestjs
        UPrepo["userProfile.repository.ts"]:::data
        UPent["user_profile.entity.ts"]:::data
        UPdto["userProfile.dto.ts"]:::data
    end

    subgraph "Category Module"
        direction TB
        CCtrl["category.controller.ts"]:::nestjs
        CService["category.service.ts"]:::nestjs
        CDto["category.dto.ts"]:::data
    end

    subgraph "Cloudinary Module"
        direction TB
        ClService["cloudinary.service.ts"]:::nestjs
        ClInterface["cloudinary.interface.ts"]:::ext
    end

    DB["SQL Database"]:::data
    CloudExt["Cloudinary"]:::ext

    Client -->|HTTP| Main
    Main --> AppMod
    AppMod --> Filter
    AppMod --> Decorator
    AppMod --> Guard
    AppMod --> Strategy

    AppMod --> UCtrl
    UCtrl -->|uses Guard| Guard
    UCtrl --> UService
    UService --> URepo
    URepo --> DB
    UService --> UEntity
    UService --> UDTO

    AppMod --> UPctrl
    UPctrl -->|uses Guard| Guard
    UPctrl --> UPsvc
    UPsvc --> UPrepo
    UPrepo --> DB
    UPsvc --> UPent
    UPsvc --> UPdto

    AppMod --> CCtrl
    CCtrl -->|uses Guard| Guard
    CCtrl --> CService
    CService --> DB
    CService --> CDto

    AppMod --> ClService
    ClService --> ClInterface
    ClService --> CloudExt

    Guard --> Strategy
    Strategy --> JwtInterface

    click Main "https://github.com/poleeast/pinpin_backend/blob/master/src/main.ts"
    click AppMod "https://github.com/poleeast/pinpin_backend/blob/master/src/app.module.ts"
    click Filter "https://github.com/poleeast/pinpin_backend/blob/master/src/common/filters/global_exception.filter.ts"
    click Decorator "https://github.com/poleeast/pinpin_backend/blob/master/src/common/decorators/api_responses.decorator.ts"
    click Guard "https://github.com/poleeast/pinpin_backend/blob/master/src/common/guards/jwt.guard.ts"
    click Strategy "https://github.com/poleeast/pinpin_backend/blob/master/src/common/strategies/jwt.strategy.ts"
    click JwtInterface "https://github.com/poleeast/pinpin_backend/blob/master/src/interfaces/jwt.interface.ts"
    click UCtrl "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/user/user.controller.ts"
    click UService "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/user/user.service.ts"
    click URepo "https://github.com/poleeast/pinpin_backend/blob/master/src/repositories/user.repository.ts"
    click UEntity "https://github.com/poleeast/pinpin_backend/blob/master/src/entities/user.entity.ts"
    click UDTO "https://github.com/poleeast/pinpin_backend/blob/master/src/dtos/user.dto.ts"
    click UPctrl "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/userProfile/userProfile.controller.ts"
    click UPsvc "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/userProfile/userProfile.service.ts"
    click UPrepo "https://github.com/poleeast/pinpin_backend/blob/master/src/repositories/userProfile.repository.ts"
    click UPent "https://github.com/poleeast/pinpin_backend/blob/master/src/entities/user_profile.entity.ts"
    click UPdto "https://github.com/poleeast/pinpin_backend/blob/master/src/dtos/userProfile.dto.ts"
    click CCtrl "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/category/category.controller.ts"
    click CService "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/category/category.service.ts"
    click CDto "https://github.com/poleeast/pinpin_backend/blob/master/src/dtos/category.dto.ts"
    click ClService "https://github.com/poleeast/pinpin_backend/blob/master/src/modules/cloudinary/cloudinary.service.ts"
    click ClInterface "https://github.com/poleeast/pinpin_backend/blob/master/src/interfaces/cloudinary.interface.ts"
```
