# kych0912/saas-starter-ko architecture

> Architecture diagram of the GitHub repository kych0912/saas-starter-ko, 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/kych0912/saas-starter-ko
- Repository: https://github.com/kych0912/saas-starter-ko

## Overview

This project is a full-stack SaaS application built with Next.js. It integrates a marketing landing page, user authentication, a user dashboard with various subpages, and payment processing using StepPay. The overall architecture leverages Next.js’s app directory for server components and API routes while integrating middleware (for auth, localization, etc.), a Postgres database with Drizzle ORM, i18n support, and a component-based UI built partly on shadcn/ui.

##### Main Components
- Client/Browser: Represents the end users accessing the app through different entry points such as the landing page, pricing page, sign-up/sign-in pages, and the dashboard.
- Next.js Frontend:
- Pages & Layouts: Highlight the directories under app/[lng] with routes for dashboard, billing, login, and marketing.
- Locale & i18n System: Represent the i18n folder that contains local translations (KO/EN) and conversion scripts.
- UI Components: Include key reusable UI elements (e.g., buttons, cards, modals, etc.) located in the components/ui folder.
- API Endpoints:
- Authentication API: Detail the NextAuth integration seen under app/api/auth and the supporting auth modules in lib/auth.
- Payment Processing: Include the StepPay checkout and webhook endpoints located in app/api/steppay, along with the corresponding business logic in lib/payments.
- Middleware:
- Global and local middleware for authentication (user, language, and session validation) found in middleware and lib/auth/middleware.ts.
- Backend Services:
- Database: A Postgres database interacting via Drizzle ORM with configuration, migrations, seed, and queries found in the lib/db folder.
- External Services: Include payment gateway StepPay and OAuth integrations for Google and NAVER authentication.

##### Relationships & Interactions
- The Client makes HTTP requests (via navigation and form submissions) to the Next.js server.
- UI pages and components consume API endpoints for retrieving and updating data (authentication, billing, dashboard operations).
- Authentication flow involves the NextAuth endpoints (handled under app/api/auth) and corresponding session/middleware logic.
- Payment processing flows:
- Users are redirected to a StepPay checkout page (via designated API endpoints) when subscribing or purchasing.
- StepPay sends webhook notifications to the app (app/api/steppay/webhook) that trigger payment state updates.
- The business logic modules in the lib folder (for auth, DB, and payments) interact with the Postgres database using Drizzle ORM.
- Localization on both the server and client is managed via the i18n system that loads JSON resources from the app/i18n/locales folder.

##### Architectural Patterns & Design Principles
- Full-stack integration: Next.js is used as both the frontend and backend framework.
- Routing architecture: Clear separation of concerns using Next.js’s file-based routing (pages for landing, dashboard, billing, etc.).
- Middleware-driven security/validation: Global and route-specific middleware ensure routes are protected.
- Modular design: Reusable UI components and business logic modules (e.g., payments and authentication) are decoupled into their own directories.
- Internationalization (i18n): Provides multi-language support by maintaining separate locale JSON files and translation hooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser("Client/Browser"):::client
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        Pages("Next.js Pages & Layouts"):::frontend
        UI("UI Components"):::frontend
        Locale("Locale & i18n System"):::frontend
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        GlobalMW("Global Middleware"):::middleware
        AuthMW("Auth Middleware"):::middleware
    end

    %% API Layer
    subgraph "API Layer"
        AuthAPI("Authentication API"):::api
        AuthLib("Auth Modules"):::api
        PaymentAPI("StepPay API Endpoint"):::api
        PaymentLib("Payment Processing Logic"):::api
    end

    %% Database Layer
    subgraph "Database Layer"
        DB("Postgres Database"):::database
    end

    %% External Services
    subgraph "External Services"
        StepPay("StepPay"):::external
        Google("Google OAuth"):::external
        Naver("NAVER OAuth"):::external
    end

    %% Relationships: Client to Frontend
    Browser -->|"accesses"| Pages
    Pages -->|"renders with"| UI
    Pages -->|"loads"| Locale

    %% Relationships: Frontend to Middleware
    Pages -->|"secured by"| GlobalMW
    Pages -->|"secured by"| AuthMW

    %% Relationships: Frontend to API
    Pages -->|"calls"| AuthAPI
    Pages -->|"calls"| PaymentAPI

    %% Relationships: API internal flow
    AuthAPI -->|"utilizes"| AuthLib
    PaymentAPI -->|"utilizes"| PaymentLib

    %% Relationships: API to Database
    AuthAPI -->|"CRUD"| DB
    PaymentAPI -->|"CRUD"| DB

    %% Relationships: External Services to API
    StepPay -->|"webhook"| PaymentAPI
    Google -->|"OAuth-callback"| AuthAPI
    Naver -->|"OAuth-callback"| AuthAPI

    %% Middleware securing API endpoints (annotation)
    GlobalMW -.->|"secures"| AuthAPI
    GlobalMW -.->|"secures"| PaymentAPI
    AuthMW -.->|"validates"| AuthAPI

    %% Click Events
    click Pages "https://github.com/kych0912/saas-starter-ko/tree/main/app/[lng]"
    click Locale "https://github.com/kych0912/saas-starter-ko/tree/main/app/i18n"
    click UI "https://github.com/kych0912/saas-starter-ko/tree/main/components/ui"
    click AuthAPI "https://github.com/kych0912/saas-starter-ko/tree/main/app/api/auth"
    click AuthLib "https://github.com/kych0912/saas-starter-ko/tree/main/lib/auth"
    click PaymentAPI "https://github.com/kych0912/saas-starter-ko/tree/main/app/api/steppay"
    click PaymentLib "https://github.com/kych0912/saas-starter-ko/tree/main/lib/payments"
    click GlobalMW "https://github.com/kych0912/saas-starter-ko/tree/main/middleware"
    click AuthMW "https://github.com/kych0912/saas-starter-ko/blob/main/lib/auth/middleware.ts"
    click DB "https://github.com/kych0912/saas-starter-ko/tree/main/lib/db"

    %% Styles
    classDef client fill:#f4b400,stroke:#333,stroke-width:2px;
    classDef frontend fill:#34a853,stroke:#333,stroke-width:2px;
    classDef middleware fill:#4285f4,stroke:#333,stroke-width:2px;
    classDef api fill:#ea4335,stroke:#333,stroke-width:2px;
    classDef database fill:#fbbc05,stroke:#333,stroke-width:2px;
    classDef external fill:#8e24aa,stroke:#333,stroke-width:2px;
```
