# lab-semtle/semtle-web-client architecture

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

- Interactive diagram: https://gitdiagram.com/lab-semtle/semtle-web-client
- Repository: https://github.com/lab-semtle/semtle-web-client

## Overview

##### Main Components
- Frontend/UI Layer:
- Pages: Located under src/app, these are the various pages organized by functions such as authentication ((auth)), user interfaces with navigation and footer ((with-navi-footer)), and executive/admin functionalities.
- Layouts: Several layout components exist, including global layouts (src/app/layout.tsx) and specialized admin and navigable layouts.
- API Layer:
- API Routes: All Next.js API endpoints are in src/app/api (authentication endpoints, file handling, folder operations, etc.).
- Authentication Module: The integration with Next Auth is evident in src/app/api/auth and supported by authentication logic placed within src/lib/auth.
- State and Business Logic:
- Hooks: Found in src/hooks, these manage state, API calls for activities, banners, projects, etc.
- Utility & Library Modules: The src/lib directory houses authentication configs, middleware, and utility functions.
- Data and Types:
- Constants and Types: Static data is maintained in src/constants and TypeScript type definitions in src/types.
- Development and Mocking Infrastructure:
- Mocks: The src/mocks directory contains the setup for mocking API responses using MSW.
- Test and Dev Configurations: Various environment configurations, ESLint, Prettier, and other dev settings exist to ensure code quality and proper build tooling.

##### Relationships and Interactions
- The UI Layer interacts with the API Layer via API routes when fetching or sending data (e.g., user authentication, file uploads/downloads through endpoints in src/app/api).
- The API endpoints use authentication middleware and mechanisms from src/lib/auth to secure routes.
- Shared logic such as validation and API clients reside in lib and hooks, creating integration points across the UI components.
- The static public folder supplies assets (images, CSS, documents) that support the rendering of the UI.
- Mocks are used during development and testing, intercepting API calls and providing predictable data for UI components.

##### Architectural Patterns and Technologies
- Next.js Page Routing: Utilizing the file-based routing mechanism in the src/app directory, including nested layouts and dynamic segments.
- Component-Based Architecture: A distinct separation into reusable, modular components (e.g., common UI components and admin-specific elements).
- API-first Interaction: Adoption of server-side APIs within the Next.js framework (including Next Auth for authentication).
- Hooks and State Management: Extensive use of custom React hooks to encapsulate and reuse stateful logic.
- Mock Service Workers (MSW): For simulating API responses during testing, indicating test-driven development practices.
- TypeScript and Tailwind CSS: TypeScript integration for type safety (src/types) and Tailwind for styling (evident from tailwind.config.ts and CSS modules).

##### Elements
- Clear Labels: Each component (e.g., "UI Pages", "Layout Components", "API Routes", "Authentication Module", "Hooks/State Management", "Mock Services") should be neatly labeled.
- Presentation (UI) components,
- Application logic (hooks, utilities),
- API services,
- External integrations (public assets, environment variables).
- Integration Points: Clearly mark where components interact—for example, how Next Auth routes link to the auth middleware, or how the API layer pulls in data from hooks.

##### Essential Architectural Elements
- Specific build or deployment configurations (e.g., next.config.ts, postcss.config.mjs) if relevant, to show how the project is set up for development and production.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer (UI)"
        UI["UI Pages"]:::presentation
        GlobalLayout["Global Layout"]:::presentation
        ExecLayout["Executive Layout"]:::presentation
        Components["Reusable UI Components"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        Hooks["Hooks/State Management"]:::logic
        Utils["Utility & Library Modules"]:::logic
    end

    %% API Layer
    subgraph "API Layer"
        APIRoutes["API Routes"]:::api
        APIAuth["API Auth"]:::api
        LibAuth["Lib Auth"]:::api
    end

    %% Data & Config Layer
    subgraph "Data & Config"
        Constants["Constants"]:::data
        Types["Type Definitions"]:::data
        Mocks["Mocking Infrastructure"]:::config
        PublicAssets["Public Assets"]:::config
    end

    %% Connections within Presentation Layer
    UI -->|"renders"| GlobalLayout
    UI -->|"renders"| ExecLayout
    GlobalLayout -->|"composes"| Components
    ExecLayout -->|"composes"| Components
    UI -->|"managesState"| Hooks
    UI -->|"fetchesData"| APIRoutes
    UI -->|"loadsAssets"| PublicAssets

    %% Business Logic interactions
    Hooks -->|"calls"| Utils
    Utils -->|"configData"| Constants
    Utils -->|"configTypes"| Types

    %% API interactions
    APIRoutes -->|"authVia"| APIAuth
    APIRoutes -->|"authVia"| LibAuth

    %% Mocks intercept API
    Mocks ---|"intercepts"| APIRoutes

    %% Class Definitions
    classDef presentation fill:#e0f7fa,stroke:#0277bd,stroke-width:2px;
    classDef logic fill:#dcedc8,stroke:#558b2f,stroke-width:2px;
    classDef api fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef data fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px;
    classDef config fill:#ffe0b2,stroke:#ef6c00,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/lab-semtle/semtle-web-client/tree/main/src/app"
    click GlobalLayout "https://github.com/lab-semtle/semtle-web-client/blob/main/src/app/layout.tsx"
    click ExecLayout "https://github.com/lab-semtle/semtle-web-client/blob/main/src/app/executive/layout.tsx"
    click Components "https://github.com/lab-semtle/semtle-web-client/tree/main/src/components"
    click APIRoutes "https://github.com/lab-semtle/semtle-web-client/tree/main/src/app/api"
    click APIAuth "https://github.com/lab-semtle/semtle-web-client/tree/main/src/app/api/auth"
    click LibAuth "https://github.com/lab-semtle/semtle-web-client/tree/main/src/lib/auth"
    click Hooks "https://github.com/lab-semtle/semtle-web-client/tree/main/src/hooks"
    click Utils "https://github.com/lab-semtle/semtle-web-client/tree/main/src/lib"
    click Constants "https://github.com/lab-semtle/semtle-web-client/tree/main/src/constants"
    click Types "https://github.com/lab-semtle/semtle-web-client/tree/main/src/types"
    click Mocks "https://github.com/lab-semtle/semtle-web-client/tree/main/src/mocks"
    click PublicAssets "https://github.com/lab-semtle/semtle-web-client/tree/main/public"
```
