# onurlulardan/nextjstemplate architecture

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

- Interactive diagram: https://gitdiagram.com/onurlulardan/nextjstemplate
- Repository: https://github.com/onurlulardan/nextjstemplate

## Overview

##### Project Type and Purpose
- This is a full-stack, multi-tenant web application built with Next.js 15 (App Router), TypeScript, Knex.js and PostgreSQL, featuring:
- Responsive UI (Ant Design)
- Advanced authentication/authorization (NextAuth.js)
- Multi-organization, role- and permission-based access control
- Real-time data sync (via React hooks/contexts)
- Security-logging of auth events

##### File Structure
- app/
- (protected)/… — all authenticated UI pages under dashboard and administrations (users, roles, permissions, organizations, security-logs)
- api/… — serverless route handlers for auth, dashboard stats, and all administration endpoints
- auth/… — login & register pages and forms
- layout.tsx, providers.tsx, globals.css — shared layouts, providers (NotificationContext), global styles
- lib/
- apiClient — typed fetch/axios wrappers with automatic `/api` prefix, retry & notification logic
- auth — NextAuth options, permission-check utilities (usePermission, requirePermission)
- utils — general helpers
- contexts/NotificationContext.tsx — React Context to broadcast UI notifications
- core/… — shared UI components (Navbar, Sidebar, DataGrid) and layout primitives
- hooks/useNotificationSetup.ts — custom hook to wire notifications into API client
- knex/… — DB layer: adapters (NextAuth-Knex), migrations, seeds, schema creation, TypeScript types for each table
- config/theme.json, tailwind.config.ts — styling/configuration
- public/… — static assets (readme images)
- next.config.ts, tsconfig.json, middleware.ts — framework config

##### Extract Architecture Insights from README
- Frontend: Next.js App Router, React + Ant Design
- Backend: Next.js API routes → NextAuth.js for session + permission checks → Knex.js → PostgreSQL
- Notification system: Ant Design + custom React Context + API client interceptors
- Permission system: hierarchical checks (admin → direct → role → organization) implemented in lib/auth/permissions

##### Diagramming the System
a. Main Components
- Client Browser (React/Next.js pages/components)
- Next.js App Server / Serverless Functions
- Authentication Service (NextAuth.js)
- API Layer (app/api route handlers)
- Business Logic / Permission Layer (lib/auth, requirePermission, usePermission)
- Database Access Layer (Knex.js adapters, seed/migration scripts)
- PostgreSQL Database
- Notification System (NotificationContext + API client intercepts)
b. Interactions & Data Flow
1. User → Browser UI component (e.g. Organizations page)
2. UI calls API client (getRequest, postRequest, etc.)
3. API client → Next.js API route (app/api/…)
4. Route Handler → requirePermission/checkPermission → NextAuth session → Knex DB adapter
5. Knex adapter → PostgreSQL
6. Response → API client → UI
7. NotificationContext displays success/error messages
c. Architectural Patterns
- App Router pattern (file-based routing)
- Serverless function endpoints (Next.js API routes)
- Layered architecture: UI → API → Auth/Permission → DB
- Context & hooks for cross-cutting concerns (notifications, auth)
- Type-safe DB access with Knex + TypeScript types
d. Technology Highlights
- Next.js 15 App Router & Route Handlers
- Ant Design UI library
- NextAuth.js with Knex adapter
- Knex.js for DB queries, migrations, seeds
- PostgreSQL as relational store
- Axios/fetch wrappers in lib/apiClient

##### Essential Details to Capture
- File-based routing structure (App Router & API routes)
- Auth path: NextAuth session → route handler → requirePermission
- Permission hierarchy rules
- Data access via Knex (adapters + TypeScript types)
- Notification interceptor in API client
- Multi-organization, multi-role relationship

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend"
        direction TB
        BrowserUI["Protected UI Pages"]:::frontend
        click BrowserUI "https://github.com/onurlulardan/nextjstemplate/tree/main/app/(protected)"
        AuthPages["Auth Pages (Login/Register)"]:::frontend
        click AuthPages "https://github.com/onurlulardan/nextjstemplate/tree/main/app/auth"
        SharedLayout["Shared Layout & Providers"]:::frontend
        click SharedLayout "https://github.com/onurlulardan/nextjstemplate/blob/main/app/layout.tsx"
        SharedProviders["Providers & Styles"]:::frontend
        click SharedProviders "https://github.com/onurlulardan/nextjstemplate/blob/main/app/providers.tsx"
        click SharedProviders "https://github.com/onurlulardan/nextjstemplate/blob/main/app/globals.css"
        subgraph "Core UI Components"
            direction TB
            DataGrid["DataGrid Component"]:::frontend
            click DataGrid "https://github.com/onurlulardan/nextjstemplate/blob/main/core/components/datagrid/index.tsx"
            Navbar["Navbar Component"]:::frontend
            click Navbar "https://github.com/onurlulardan/nextjstemplate/blob/main/core/layout/components/Navbar.tsx"
            Sidebar["Sidebar Component"]:::frontend
            click Sidebar "https://github.com/onurlulardan/nextjstemplate/blob/main/core/layout/components/Sidebar.tsx"
        end
        NotificationContext["NotificationContext"]:::notification
        click NotificationContext "https://github.com/onurlulardan/nextjstemplate/blob/main/contexts/NotificationContext.tsx"
        NotificationHook["useNotificationSetup Hook"]:::notification
        click NotificationHook "https://github.com/onurlulardan/nextjstemplate/blob/main/hooks/useNotificationSetup.ts"
        APIClient["API Client Wrapper"]:::frontend
        click APIClient "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/apiClient/index.ts"
        click APIClient "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/apiClient/types/types.ts"
    end

    %% Backend Layer
    subgraph "Backend"
        direction TB
        subgraph "API Routes"
            direction TB
            AuthRoute["NextAuth Route"]:::api
            click AuthRoute "https://github.com/onurlulardan/nextjstemplate/blob/main/app/api/auth/[...nextauth]/route.ts"
            RegisterRoute["Register Route"]:::api
            click RegisterRoute "https://github.com/onurlulardan/nextjstemplate/blob/main/app/api/auth/register/route.ts"
            StatsRoute["Dashboard Stats Route"]:::api
            click StatsRoute "https://github.com/onurlulardan/nextjstemplate/blob/main/app/api/dashboard/stats/route.ts"
            AdminRoutes["Administration Routes"]:::api
            click AdminRoutes "https://github.com/onurlulardan/nextjstemplate/tree/main/app/api/administrations/**"
        end
        AuthService["NextAuth.js Service"]:::logic
        click AuthService "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/auth/auth-options.ts"
        PermissionClient["Client-permission Utils"]:::logic
        click PermissionClient "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/auth/client-permissions.ts"
        click PermissionClient "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/auth/utils.ts"
        PermissionServer["Server-permission Checks"]:::logic
        click PermissionServer "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/auth/server-permissions.ts"
        AuthTypes["Auth Types"]:::logic
        click AuthTypes "https://github.com/onurlulardan/nextjstemplate/blob/main/lib/auth/types.ts"
        subgraph "DB Layer"
            direction TB
            KnexAdapter["NextAuth Knex Adapter"]:::logic
            click KnexAdapter "https://github.com/onurlulardan/nextjstemplate/blob/main/knex/adapters/nextauth-knex-adapter.ts"
            KnexEntry["Knex Entry & Setup"]:::logic
            click KnexEntry "https://github.com/onurlulardan/nextjstemplate/blob/main/knex/index.ts"
            click KnexEntry "https://github.com/onurlulardan/nextjstemplate/blob/main/knex/setdb.ts"
            Migrations["Migrations & Seeds"]:::logic
            click Migrations "https://github.com/onurlulardan/nextjstemplate/blob/main/knex/seed.ts"
            TableTypes["Table Types"]:::logic
            click TableTypes "https://github.com/onurlulardan/nextjstemplate/blob/main/knex/types/*.ts"
        end
        Postgres["PostgreSQL Database"]:::db
    end

    %% Connections
    BrowserUI -->|uses| APIClient
    AuthPages -->|uses| APIClient
    APIClient -->|calls /api| AuthRoute
    APIClient -->|calls /api| RegisterRoute
    APIClient -->|calls /api| StatsRoute
    APIClient -->|calls /api| AdminRoutes

    AuthRoute -->|session| AuthService
    RegisterRoute -->|session| AuthService
    StatsRoute -->|permission check| PermissionServer
    AdminRoutes -->|permission check| PermissionServer

    AuthService -->|uses| KnexAdapter
    PermissionServer -->|uses| AuthService
    PermissionServer -->|uses| KnexAdapter

    KnexAdapter -->|DB queries| KnexEntry
    KnexEntry -->|runs| Migrations
    KnexEntry -->|types| TableTypes
    KnexEntry -->|connects| Postgres

    %% Notification Flow
    APIClient -->|intercepts| NotificationContext
    NotificationContext -->|consumes| NotificationHook

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef api fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef logic fill:#FFF3C4,stroke:#333,stroke-width:1px
    classDef notification fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef db fill:#C0C0C0,stroke:#333,stroke-width:1px
```
