# airli1507/qsis-3 architecture

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

- Interactive diagram: https://gitdiagram.com/airli1507/qsis-3
- Repository: https://github.com/airli1507/qsis-3

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (App Router).
- It provides user authentication (login, logout, password reset), and a protected dashboard with several sub-pages (homework, reading, profile, settings, etc.).
- The file tree uses Next.js’s file-based routing for both UI pages (`src/app/.../page.tsx`) and server API routes (`src/app/auth/login.ts`, `src/app/auth/refresh.ts`).

##### High-Level Architecture Components
a. Client (Browser)
- Loads initial HTML & CSS from Next.js server.
- Hydrates React components for client-side interactivity.
- Calls internal API routes for auth and data fetching.
b. Next.js Server (Node/Vercel Serverless)
- Renders React pages server-side (SSR).
- Hosts API route handlers under `src/app/auth/*.ts`.
- Serves static assets from `public/`.
c. UI Layer
- Page components in `src/app/**/page.tsx`.
- Layout components (`layout.tsx`) that wrap pages (global and per-segment).
- Shared React components in `src/components/` (AuthWrapper, Dashboard sidebar/tab, Brand logo).
d. Business Logic & Utilities
- `src/utils/login.ts`, `logout.ts`, `refresh.ts` encapsulate API-calling and token handling.
- `src/i18n/request.ts` manages internationalization requests.
e. Data & External Services
- (Implied) Authentication store or third-party identity provider behind `login`/`refresh` API.
- Potential database or external API flows (not included in code, plan for placeholder).

##### Architectural Patterns & Principles
- File-based routing (Next.js App Router) separates UI pages and server APIs by directory.
- Layout composition: global, auth-segment, dashboard-segment layouts provide shared wrappers and protected routing.
- React Context (`src/app/context.tsx`) centralizes auth state across client & server.
- Separation of concerns: UI components vs. business-logic utilities vs. route handlers.
- Monorepo/Workspace via pnpm (pnpm-workspace.yaml) suggests possible multi-package future extension.

- Use rectangles for “Browser Client,” “Next.js Server (SSR + API),” “UI Components,” “Business Logic Layer,” and “External Services/DB.”
– Frontend (light blue)
– Backend (light green)
– External/DB (gray)
c. Labels & Details
- API route handlers under “Auth API” with filenames.
- `Context` node feeding auth state into UI Components.
- Blue rectangles for client-side React & layouts.
- Green for server-side route handlers & utilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier" 
        direction TB
        Browser["Browser Client"]:::frontend
        Static["Static Assets\n(public/)"]:::frontend
    end
    click Static "https://github.com/airli1507/qsis-3/tree/main/public/"

    %% Server Tier
    subgraph "Server Tier"
        direction TB

        NextServer["Next.js Server\n(SSR + API)"]:::backend

        subgraph "UI Rendering"
            direction TB
            GlobalLayout["Global App Layout\nsrc/app/layout.tsx"]:::backend
            EntryPage["Entry Page\nsrc/app/page.tsx"]:::backend
            GlobalsCSS["Global Styles\nsrc/app/globals.css"]:::backend
        end
        click GlobalLayout "https://github.com/airli1507/qsis-3/blob/main/src/app/layout.tsx"
        click EntryPage "https://github.com/airli1507/qsis-3/blob/main/src/app/page.tsx"
        click GlobalsCSS "https://github.com/airli1507/qsis-3/blob/main/src/app/globals.css"

        subgraph "Auth UI Pages & Layout"
            direction TB
            AuthLayout["Auth Layout\nsrc/app/(auth)/layout.tsx"]:::frontend
            LoginPage["Login Page\nsrc/app/(auth)/login/page.tsx"]:::frontend
            LogoutPage["Logout Page\nsrc/app/(auth)/logout/page.tsx"]:::frontend
            ResetPage["Reset Page\nsrc/app/(auth)/reset/page.tsx"]:::frontend
        end
        click AuthLayout "https://github.com/airli1507/qsis-3/blob/main/src/app/(auth)/layout.tsx"
        click LoginPage "https://github.com/airli1507/qsis-3/blob/main/src/app/(auth)/login/page.tsx"
        click LogoutPage "https://github.com/airli1507/qsis-3/blob/main/src/app/(auth)/logout/page.tsx"
        click ResetPage "https://github.com/airli1507/qsis-3/blob/main/src/app/(auth)/reset/page.tsx"

        subgraph "Dashboard UI Pages & Layout"
            direction TB
            DashboardLayout["Dashboard Layout\nsrc/app/dashboard/layout.tsx"]:::frontend
            DashboardHome["Dashboard Home\nsrc/app/dashboard/page.tsx"]:::frontend
            ProfilePage["Profile\nsrc/app/dashboard/[profile]/page.tsx"]:::frontend
            HomeworkPage["Homework\nsrc/app/dashboard/homework/page.tsx"]:::frontend
            ReadingPage["Reading\nsrc/app/dashboard/reading/page.tsx"]:::frontend
            ProfileSettings["Settings\nsrc/app/dashboard/settings/page.tsx"]:::frontend
            AlbumPage["Album\nsrc/app/dashboard/album/page.tsx"]:::frontend
            ECPage["EC\nsrc/app/dashboard/ec/page.tsx"]:::frontend
            SSPage["SS\nsrc/app/dashboard/ss/page.tsx"]:::frontend
        end
        click DashboardLayout "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/layout.tsx"
        click DashboardHome "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/page.tsx"
        click ProfilePage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/[profile]/page.tsx"
        click HomeworkPage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/homework/page.tsx"
        click ReadingPage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/reading/page.tsx"
        click ProfileSettings "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/settings/page.tsx"
        click AlbumPage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/album/page.tsx"
        click ECPage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/ec/page.tsx"
        click SSPage "https://github.com/airli1507/qsis-3/blob/main/src/app/dashboard/ss/page.tsx"

        subgraph "Auth API Routes"
            direction TB
            LoginAPI["login.ts\nsrc/app/auth/login.ts"]:::backend
            RefreshAPI["refresh.ts\nsrc/app/auth/refresh.ts"]:::backend
        end
        click LoginAPI "https://github.com/airli1507/qsis-3/blob/main/src/app/auth/login.ts"
        click RefreshAPI "https://github.com/airli1507/qsis-3/blob/main/src/app/auth/refresh.ts"

        subgraph "Business Logic & Utilities"
            direction TB
            LoginUtil["login.ts\nsrc/utils/login.ts"]:::backend
            LogoutUtil["logout.ts\nsrc/utils/logout.ts"]:::backend
            RefreshUtil["refresh.ts\nsrc/utils/refresh.ts"]:::backend
            I18n["i18n req\nsrc/i18n/request.ts"]:::backend
        end
        click LoginUtil "https://github.com/airli1507/qsis-3/blob/main/src/utils/login.ts"
        click LogoutUtil "https://github.com/airli1507/qsis-3/blob/main/src/utils/logout.ts"
        click RefreshUtil "https://github.com/airli1507/qsis-3/blob/main/src/utils/refresh.ts"
        click I18n "https://github.com/airli1507/qsis-3/blob/main/src/i18n/request.ts"

        Context["Auth Context\nsrc/app/context.tsx"]:::frontend
        click Context "https://github.com/airli1507/qsis-3/blob/main/src/app/context.tsx"

        Wrapper["Protected Route Wrapper\nsrc/app/wrapper.tsx"]:::frontend
        click Wrapper "https://github.com/airli1507/qsis-3/blob/main/src/app/wrapper.tsx"
    end

    %% Data/External Tier
    subgraph "Data & External Services"
        direction TB
        AuthDB["Auth Service / DB"]:::external
    end

    %% Connections
    Browser -->|HTTP GET page| NextServer
    Browser -->|fetch static| Static
    NextServer --> GlobalLayout
    NextServer --> EntryPage
    NextServer -->|serves CSS| GlobalsCSS

    EntryPage --> Context
    Context --> AuthLayout
    Context --> DashboardLayout
    AuthLayout --> LoginPage
    AuthLayout --> LogoutPage
    AuthLayout --> ResetPage

    DashboardLayout --> DashboardHome
    DashboardLayout --> ProfilePage
    DashboardLayout --> HomeworkPage
    DashboardLayout --> ReadingPage
    DashboardLayout --> ProfileSettings
    DashboardLayout --> AlbumPage
    DashboardLayout --> ECPage
    DashboardLayout --> SSPage

    Browser -->|POST /auth/login| LoginAPI
    Browser -->|POST /auth/refresh| RefreshAPI
    LoginAPI --> LoginUtil
    RefreshAPI --> RefreshUtil
    LoginUtil --> AuthDB
    RefreshUtil --> AuthDB

    GlobalLayout --> I18n
    I18n --> AuthDB

    Wrapper --> DashboardLayout

    classDef frontend fill:#ccf,stroke:#333,stroke-width:1px
    classDef backend fill:#cfc,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
```
