# questspace-v2/questspace-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/questspace-v2/questspace-frontend
- Repository: https://github.com/questspace-v2/questspace-frontend

## Overview

##### Project Type & Purpose
- This is a frontend application built using Next.js. Its purpose is to serve as a “Движок для создания и проведения квестов” (an engine for creating and conducting quests).
- It supports quest catalog browsing, interactive gameplay with tasks and hints, team management with invites, an admin dashboard (e.g., leaderboard, logs), and authentication (via standard login or Google OAuth).

##### Analyzing the File Structure
- The “app/api” directory holds API endpoints, including authentication endpoints under “auth/[...nextauth]” (indicating integration with NextAuth) alongside other API utilities (like client setups, constants, and custom error handling).
- The “components” directory is highly modularized and organizes UI components (for Auth forms, Header, Footer, quest-related components, tasks, themes, etc.). This separation shows a component-driven architecture.
- Additional folders like “lib” (for fonts, theme configuration, utility functions) and “types” (for TypeScript definitions and next-auth extensions) further encapsulate cross-cutting concerns.
- The presence of “infra/k8s” and GitHub workflows (in the .github folder) illustrate the project's deployment and CI/CD configurations using Docker and Kubernetes deployments.
- Other configuration files (next.config.js, jest.config.js, tsconfig.json, etc.) indicate build, type-checking, and testing setups.

##### Interpreting the README
- The README summarizes the application features (quest catalog, gameplay, team invitations, customizable quests/tasks, authentication using NextAuth) showing the overall flow for both end users and administrators.
- The startup instructions confirm that the application is built with Node.js and Next.js – reinforcing the frontend nature of the project.

a. Main Components:
- Next.js Frontend Application:
- Presentation Layer: All pages and layouts under the “app/(root)” and “app/(auth and errors)” directories.
- Routing & Views: Multiple dynamic routes handling quest listings, quest creation, editing, play mode, and error pages.
- API Endpoints:
- API Layer: API routes under “app/api” (especially authentication with NextAuth and other client endpoints).
- UI Component Module:
- Reusable Components: Found in “components” directory including AuthForm, Header, Footer, Quest modules (editing, preview, admin panels), Tasks, etc.
- Global Utilities & Theming:
- “lib/theme”, “globals”, and “types” contribute to UI theming, styling, and type safety across the app.
- Infrastructure & Deployment:
- CI/CD Pipeline: GitHub workflows defined under “.github/workflows” for deployment and testing.
- Containerization: Dockerfile and associated configs indicate containerized deployments.
- Kubernetes Manifests: YAML files under “infra/k8s/questspace” define the deployment of frontend services.
- Authentication Service:
- NextAuth integration through API route “app/api/auth/[...nextauth]”.
- NextAuthProvider component in “components/NextAuthProvider” to wrap and manage session contexts.

b. Relationships & Interactions:
- The browser interacts with the Next.js frontend, which renders pages using the React component hierarchy.
- The frontend makes API calls to the internal API endpoints (e.g., for authentication and quest data), some of which are handled by NextAuth.
- UI components call utility functions from “lib/utils” and utilize theming via “lib/theme”.
- Deployment and configuration management (Docker, Kubernetes YAML) ensure the frontend is correctly containerized and orchestrated.
- External authentication (Google OAuth) and potentially external services are integrated via NextAuth.

c. Architectural Patterns & Design Principles:
- Component-Based Architecture: Well-modularized React components grouped by functionality.
- Routing-driven Page Structure: Next.js file-based routing, using segmented dashboards for various quest tasks.
- API Abstraction: Separation between the presentation layer and API endpoints (even if within the same codebase) to abstract business logic.
- CI/CD and Containerization: Modern deployment strategies using Docker, GitHub Actions, and Kubernetes.

d. Technologies & Frameworks in Play:
- Next.js (React) for both server-side and client-side rendering.
- TypeScript for type safety.
- NextAuth for authentication.
- SCSS/CSS Modules for styling.
- Testing with Jest (configuration files present).
- Docker and Kubernetes for deployment management.
- GitHub Actions for CI/CD pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    BROWSER["User Browser"]:::external

    subgraph "Next.js Frontend Application"
        FE1["Auth & Errors Pages"]
        FE2["General Layout & Quest Pages"]
    end

    subgraph "API Endpoints"
        API1["API Handlers"]
        API2["NextAuth Endpoints"]
    end

    subgraph "UI Components"
        UC1["Reusable UI Components"]
    end

    subgraph "Global Utilities & Theming"
        GU1["Theme Config"]
        GU2["Utility Functions"]
        GU3["Global Styling"]
        GU4["Type Definitions"]
    end

    subgraph "Infrastructure & Deployment"
        INF1["CI/CD Pipeline"]
        INF2["Containerization Setup"]
        INF3["Kubernetes Manifests"]
    end

    subgraph "Authentication Service"
        AUTH1["NextAuth Provider"]
    end

    %% Relationships
    BROWSER -->|"accesses"| FE2
    FE2 -->|"renders"| FE1
    FE2 -->|"calls"| UC1
    FE2 -->|"invokes"| API1
    FE2 -->|"invokes"| API2
    FE2 -->|"utilizes"| GU1
    FE2 -->|"utilizes"| GU2
    FE2 -->|"styles with"| GU3
    FE2 -->|"typed by"| GU4
    UC1 -->|"integrates"| AUTH1
    UC1 -->|"fetches data"| API1
    AUTH1 -->|"communicates with"| API2
    %% Deployment relationships (supporting configuration)
    INF1 -->|"deploys"| FE2
    INF2 -->|"packages"| FE2
    INF3 -->|"orchestrates"| FE2

    %% Click Events
    click FE1 "https://github.com/questspace-v2/questspace-frontend/tree/main/app/(auth and errors)"
    click FE2 "https://github.com/questspace-v2/questspace-frontend/tree/main/app/(root)"
    click API1 "https://github.com/questspace-v2/questspace-frontend/tree/main/app/api"
    click API2 "https://github.com/questspace-v2/questspace-frontend/blob/main/app/api/auth/[...nextauth]"
    click UC1 "https://github.com/questspace-v2/questspace-frontend/tree/main/components"
    click GU1 "https://github.com/questspace-v2/questspace-frontend/tree/main/lib/theme"
    click GU2 "https://github.com/questspace-v2/questspace-frontend/tree/main/lib/utils"
    click GU3 "https://github.com/questspace-v2/questspace-frontend/tree/main/globals"
    click GU4 "https://github.com/questspace-v2/questspace-frontend/tree/main/types"
    click INF1 "https://github.com/questspace-v2/questspace-frontend/tree/main/.github/workflows"
    click INF2 "https://github.com/questspace-v2/questspace-frontend/tree/main/Dockerfile"
    click INF3 "https://github.com/questspace-v2/questspace-frontend/tree/main/infra/k8s/questspace"
    click AUTH1 "https://github.com/questspace-v2/questspace-frontend/tree/main/components/NextAuthProvider"

    %% Styles
    classDef external fill:#FFECB3,stroke:#FF6F00,stroke-width:2px;
    classDef frontend fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef api fill:#F1F8E9,stroke:#33691E,stroke-width:2px;
    classDef components fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef utilities fill:#F3E5F5,stroke:#4A148C,stroke-width:2px;
    classDef infra fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef auth fill:#FFEBEE,stroke:#B71C1C,stroke-width:2px;

    class FE1,FE2 frontend;
    class API1,API2 api;
    class UC1 components;
    class GU1,GU2,GU3,GU4 utilities;
    class INF1,INF2,INF3 infra;
    class AUTH1 auth;
    class BROWSER external
```
