# aungphyoex/turbo-npn architecture

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

- Interactive diagram: https://gitdiagram.com/aungphyoex/turbo-npn
- Repository: https://github.com/aungphyoex/turbo-npn

## Overview

##### Project Type and Purpose
- This is a full-stack, monorepo application built with Turborepo.
- Backend (“apps/api”) uses NestJS + TypeORM + PostgreSQL + JWT + Nodemailer + Amazon S3 utilities.
- Frontend (“apps/web”) uses Next.js v15 with React, Shadcn/UI, TailwindCSS, server-side rendering, NextAuth.
- Shared packages under “packages/…” provide reusable TypeScript configs, ESLint configs, UI components, and utility functions.

##### File-Structure Insights
- Top-level:
- apps/ – contains api (NestJS) and web (Next.js).
- packages/ – shared modules: shadcn (UI library), ts-config, eslint-config, utils, constants.
- assets/ – static media for README or build.
- apps/api follows a modular, layered MVC pattern:
- src/common – global decorators, guards, interceptors, pipes, utils.
- src/database – database module and transaction service.
- src/features – domain modules (auth, users, file, mail, health).
- apps/web follows Next.js App Router structure:
- app/ – route files and endpoints.
- components/, lib/, server/ – shared React components, client/server data-access helpers.
- Mono-repo orchestration via turbo.json and pnpm-workspace.yaml.

a. Main Components:
- Web Client (Next.js)
- API Server (NestJS)
- PostgreSQL Database
- Email Service (SMTP via Nodemailer)
- Object Storage (Amazon S3)
- Shared Libraries (UI, Utils, Configs)
- Authentication (JWT Access & Refresh Tokens)
- Turborepo/Caching Layer (build orchestration)
b. Relationships & Data Flows:
- Web Client → HTTP/HTTPS → API Server (REST endpoints + NextAuth callbacks)
- API Server → TypeORM → PostgreSQL
- API Server → Nodemailer → SMTP provider
- API Server → S3 utilities → Amazon S3 bucket (file upload/download)
- Web Client & API Server both import from Shared Packages
- Monorepo tooling (pnpm, Turborepo) orchestrates builds & caching
c. Architectural Patterns & Principles:
- Monolithic Micro-Frontend: separate apps under one repo with shared libs
- Layered MVC in API: Controllers → Services → Repositories → DB
- Next.js App Router with nested layout & API routes
- Dependency Injection in NestJS modules
- Token-based security via JWT guards and refresh mechanism
- Module boundaries for features (auth, users, mail, file, health)
d. Key Technologies & Frameworks:
- Backend: NestJS, TypeORM, PostgreSQL, JWT, Nodemailer, SWC
- Frontend: Next.js v15, React, Shadcn/UI, TailwindCSS, NextAuth, SWC
- Packaging: pnpm workspaces, Turborepo
- Shared: TypeScript, ESLint, Prettier, Husky, Commitizen

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (apps/web)"
        direction TB
        Web["Next.js Web App"]:::frontend
        NextAuthRoute["NextAuth API Route"]:::frontend
        WebServerHelpers["Server Helpers"]:::frontend
        WebClientLib["Client Libraries"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (apps/api)"
        direction TB
        API["NestJS API Server"]:::backend

        subgraph "API Modules"
            direction TB
            Auth["Auth Feature Module"]:::backend
            Users["Users Feature Module"]:::backend
            File["File Feature Module"]:::backend
            Mail["Mail Feature Module"]:::backend
            Health["Health Check Module"]:::backend
        end

        subgraph "Common Utilities"
            direction TB
            GlobalUtils["Global Common Utilities"]:::backend
            JWTAuthGuard["JWT Auth Guard"]:::backend
            JWTRefreshGuard["JWT Refresh Guard"]:::backend
            EmailServiceModule["Email Service Module"]:::backend
            S3Utils["Amazon S3 Utilities"]:::backend
            DBModule["PostgreSQL Database Module"]:::backend
        end
    end

    %% Shared Packages
    subgraph "Shared Packages (packages)"
        direction TB
        Shadcn["shadcn/UI Library"]:::shared
        UtilsPack["Shared Utilities"]:::shared
        ConstPack["Shared Constants"]:::shared
        TSConfig["TypeScript Configs"]:::shared
        ESLintConfig["ESLint Configs"]:::shared
    end

    %% External Services
    PostgreSQL[(PostgreSQL)]:::external
    S3[(Amazon S3)]:::external
    SMTP((SMTP Email)):::external
    Turborepo["Turborepo & pnpm"]:::shared

    %% Connections
    Web -->|HTTP/HTTPS| API
    NextAuthRoute -->|Auth Callbacks| API
    API -->|uses| DBModule
    DBModule -->|TypeORM| PostgreSQL
    API -->|sends email| EmailServiceModule
    EmailServiceModule -->|SMTP| SMTP
    API -->|file ops| S3Utils
    S3Utils -->|AWS SDK| S3

    Web -->|imports| Shadcn
    Web -->|imports| UtilsPack
    Web -->|imports| ConstPack
    API -->|imports| UtilsPack
    API -->|imports| ConstPack
    API -->|imports| TSConfig
    API -->|imports| ESLintConfig

    Turborepo -->|orchestrates| Web
    Turborepo -->|orchestrates| API

    API -->|guards| JWTAuthGuard
    API -->|guards| JWTRefreshGuard
    API -->|uses common| GlobalUtils

    %% Click Events
    click Web "https://github.com/aungphyoex/turbo-npn/tree/main/apps/web"
    click API "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api"
    click DBModule "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/database"
    click EmailServiceModule "https://github.com/aungphyoex/turbo-npn/blob/main/apps/api/src/common/modules/node-mailer.module.ts"
    click S3Utils "https://github.com/aungphyoex/turbo-npn/blob/main/apps/api/src/common/utils/amazon-s3.ts"
    click Auth "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/features/auth"
    click Users "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/features/users"
    click File "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/features/file"
    click Mail "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/features/mail"
    click Health "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/features/health"
    click JWTAuthGuard "https://github.com/aungphyoex/turbo-npn/blob/main/apps/api/src/common/guards/jwt-auth.guard.ts"
    click JWTRefreshGuard "https://github.com/aungphyoex/turbo-npn/blob/main/apps/api/src/common/guards/jwt-refresh.guard.ts"
    click GlobalUtils "https://github.com/aungphyoex/turbo-npn/tree/main/apps/api/src/common"
    click NextAuthRoute "https://github.com/aungphyoex/turbo-npn/blob/main/apps/web/app/api/auth/[...nextauth]/route.ts"
    click Shadcn "https://github.com/aungphyoex/turbo-npn/tree/main/packages/shadcn"
    click UtilsPack "https://github.com/aungphyoex/turbo-npn/tree/main/packages/utils"
    click ConstPack "https://github.com/aungphyoex/turbo-npn/tree/main/packages/constants"
    click TSConfig "https://github.com/aungphyoex/turbo-npn/tree/main/packages/ts-config"
    click ESLintConfig "https://github.com/aungphyoex/turbo-npn/tree/main/packages/eslint-config"
    click Turborepo "https://github.com/aungphyoex/turbo-npn/blob/main/pnpm-workspace.yaml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D8F8D0,stroke:#228B22,color:#228B22
    classDef shared fill:#EEEEEE,stroke:#999999,color:#333333
    classDef external fill:#FFE0B2,stroke:#FF8C00,color:#FF8C00
```
