# yuragb/next architecture

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

- Interactive diagram: https://gitdiagram.com/yuragb/next
- Repository: https://github.com/yuragb/next

## Overview

This project is a full-stack Next.js application built with TypeScript that leverages several modern web development technologies. In addition to using Next Auth for seamless authentication, it incorporates NextUI for its UI components, ZOD for robust schema validation, and Prisma as its ORM for managing the database. The project is well-equipped with testing frameworks (both unit tests using Jest and e2e tests with Cypress), and it follows strong code quality practices using Husky and commitlint, all integrated with CI/CD pipelines via GitHub Actions.

##### Main Components
a. Frontend (Next.js UI)
- Located in the “src/app” directory, which contains pages, locale-specific paths, and feature modules (such as authentication pages, blog, contacts, fairy tales, and admin dashboards).
- Additional UI components reside in “src/components” and feature-specific modules under “src/modules”.
- Context providers (under “src/context”) handle state management, including authentication state, internationalization (i18n), and UI themes (e.g., themeSwitcher).

b. Backend/API Layer
- API routes exist within “src/api”, handling aspects such as authentication (with Next Auth) and any ad hoc API service.
- More complex business logic and server-side operations (actions like email sending, password resets, user management, posts, comments, etc.) are contained in “src/server/actions”. These actions interface with the database and perform the bulk of backend business processing.

c. Database
- The “prisma” folder contains the database schema and model definitions (e.g., user, post, session, category, slider, tale), indicating that Prisma is used as the ORM.

d. External Services & Integrations
- Next Auth for user authentication.
- Email service components (in “emails” and “src/EmailSender”) likely integrate with an external emailing service (possibly Resend).
- Third-party UI libraries like NextUI and testing integrations via Jest and Cypress.

e. Testing, CI/CD, and Developer Tools
- Testing is extensively covered through unit tests (“__test__”), component tests, and end-to-end tests (Cypress).
- CI/CD configuration files exist in “.github/workflows” for automated code quality checks and builds.
- Development tools such as ESLint (.eslintrc.cjs), Husky (commit hooks), Prettier (.prettierrc.mjs), and commitlint ensure code standards and automated testing before commits.

##### Out Relationships and Interactions
- The Frontend (Next.js pages and UI components) communicates with the Backend/API Layer via Next.js API routes and server actions.
- Server actions invoke Prisma to interact with the Database for CRUD operations, user authentication data, and more.
- Authentication (using Next Auth) is integrated into both the frontend and backend, managing user sessions across the application.
- External services like the Email Sender interact with server actions, initiating email workflows (e.g., for password reset or registration confirmations).
- Testing tools provide feedback loops that help validate components and end-to-end user flows, while CI/CD pipelines automate deployment checks.

##### Architectural Patterns and Design Principles
- Clear separation of concerns: UI components, business logic (server actions), and data persistence layers (Prisma/Database) are well isolated.
- Modular design: Each feature (e.g., authentication, blog, contacts, admin panels) is arranged in its own folder structure, enabling scalability and easier maintenance.
- Use of contextual providers: Centralized management of cross-cutting concerns like authentication and internationalization.
- Emphasis on developer quality through rigorous code linting, formatting, and pre-commit hooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE1["Pages & Feature Modules"]:::frontend
        FE2["UI Components"]:::frontend
        FE3["Context Providers"]:::frontend
    end

    subgraph "Backend/API Layer"
        BE1["API Routes"]:::backend
        BE1A["Authentication Routes"]:::backend
        BE2["Server Actions"]:::backend
        BE3["Email Service: Emails"]:::backend
        BE4["Email Sender"]:::backend
    end

    subgraph "Database Layer"
        DB1["Database (Prisma ORM)"]:::database
    end

    subgraph "Testing"
        T1["Unit Tests"]:::testing
        T2["E2E Tests"]:::testing
    end

    subgraph "CI/CD"
        CI1["CI/CD Pipelines"]:::cicd
    end

    subgraph "Developer Tools"
        DT_Husky["Husky"]:::cicd
        DT_ESLint["ESLint"]:::cicd
        DT_Pretty["Prettier"]:::cicd
        DT_Commitlint["Commitlint"]:::cicd
    end

    %% Connections between layers
    FE1 -->|"UserRequest"| BE1
    FE2 -->|"UserInteraction"| BE1
    FE3 -->|"AuthState"| BE1A
    BE1 -->|"Handles"| BE1A
    BE1 -->|"Invokes"| BE2
    BE2 -->|"CRUDOps"| DB1
    BE2 -->|"Triggers"| BE4
    BE4 -->|"Sends"| BE3

    %% Testing and CI/CD interactions
    T1 -->|"TestsFrontend"| FE1
    T1 -->|"TestsBusinessLogic"| BE2
    T2 -->|"TestsUI"| FE2
    T2 -->|"TestsAPI"| BE1
    CI1 -->|"Automates"| FE1
    CI1 -->|"Automates"| BE1
    DT_Husky -->|"Hooks"| FE1
    DT_ESLint -->|"Lints"| BE2
    DT_Pretty -->|"Formats"| FE2
    DT_Commitlint -->|"ValidatesCommits"| BE1

    %% Click Events for component mapping
    click FE1 "https://github.com/yuragb/next/tree/master/src/app"
    click FE2 "https://github.com/yuragb/next/tree/master/src/components"
    click FE3 "https://github.com/yuragb/next/tree/master/src/context"
    click BE1 "https://github.com/yuragb/next/tree/master/src/app/api"
    click BE1A "https://github.com/yuragb/next/tree/master/src/app/api/auth"
    click BE2 "https://github.com/yuragb/next/tree/master/src/server/actions"
    click BE3 "https://github.com/yuragb/next/tree/master/emails"
    click BE4 "https://github.com/yuragb/next/tree/master/src/EmailSender"
    click DB1 "https://github.com/yuragb/next/tree/master/prisma"
    click T1 "https://github.com/yuragb/next/tree/master/__test__"
    click T2 "https://github.com/yuragb/next/tree/master/cypress"
    click CI1 "https://github.com/yuragb/next/tree/master/.github/workflows"
    click DT_Husky "https://github.com/yuragb/next/blob/master/.husky"
    click DT_ESLint "https://github.com/yuragb/next/blob/master/.eslintrc.cjs"
    click DT_Pretty "https://github.com/yuragb/next/blob/master/.prettierrc.mjs"
    click DT_Commitlint "https://github.com/yuragb/next/blob/master/commitlint.config.cjs"

    %% Styling
    classDef frontend fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef testing fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef cicd fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
```
