# ww-side/structify-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/ww-side/structify-frontend
- Repository: https://github.com/ww-side/structify-frontend

## Overview

##### Project Type and Purpose
- This is a full‑stack web application built with Next.js (React) serving both server‑side rendered (SSR) and client‑side rendered (CSR) pages.
- It uses Apollo Client to talk to a GraphQL backend (not contained in this repo), and implements authentication, user management, theming, and a feature‑driven UI (calendar, views, rows, columns, etc.).

##### Key Architectural Layers (derived from file tree)
- Presentation Layer (src/app): Next.js “app” routes, layouts, pages.
- Cross‑Cutting Core (src/core):
- api (Apollo provider)
- auth (sign‑in, sign‑up, token refresh, auth guard)
- theme (theme switcher, context)
- user (get‑me, update, logout, store)
- Feature Modules (src/features): Calendar, Columns, Create‑View, Rows, Row‑Value, Sidebar, View—each with its own components, lib (schemas/types), and service layer (actions, stores).
- Widgets (src/widgets): Page‑specific widget compositions (auth layouts, home widgets, settings, views).

##### Main Components
A. Next.js Application
- SSR Engine (Node.js at server startup)
- Client bundle (served to browser)
B. UI Component Tree
- Page Layouts (src/app/layout.tsx)
- Widgets & Feature Components
C. State & Data Layer
- Apollo Client (src/core/api/apollo-provider.tsx)
- React context/providers (Auth Guard, Theme)
- Feature stores and services (e.g., calendarEvents.store, user.store)
D. External Services
- GraphQL API endpoint
- Authentication service (could be part of GraphQL or external OAuth)
- Database (behind the GraphQL server)
E. Hosting/CI (Vercel)

##### Relationships and Data Flow
- User’s browser → HTTP request → Next.js server
- SSR resolves protected routes via Auth Guard → renders initial HTML.
- Client bundle loads → React hydrates
- Apollo Provider wraps app → feature components dispatch GraphQL queries/mutations.
- GraphQL requests → GraphQL server → Database → back to client.
- Auth flows (sign‑in/sign‑up/refresh) → Auth mutations → tokens stored in cookies or in-memory store → Auth Guard on client & server reads token.
- Theme toggles update Theme Context → persisted via local storage or context state.

##### Architectural Patterns & Principles
- Feature‑Driven Modularization: Each business domain has its own folder with clear boundaries.
- Atomic Design for UI Kit: Shared UI components are small (buttons, inputs) and composed into larger widgets.
- Provider Pattern: ApolloProvider, AuthGuard, ThemeProvider wrap the component tree.
- Separation of Concerns:
- UI (components)
- Data (services/actions/stores)
- Types/Validation (lib/schemas)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main Application
    NextApp["Next.js App"]:::service
    click NextApp "https://github.com/ww-side/structify-frontend/tree/main//"

    subgraph "Next.js App"
        %% Server-Side
        subgraph "Server-Side (SSR)"
            SSR["SSR Engine"]:::service
            AuthGuardSS["AuthGuard"]:::service
            click AuthGuardSS "https://github.com/ww-side/structify-frontend/blob/main/src/core/auth/components/auth-guard.tsx"
        end

        %% Client-Side
        subgraph "Client-Side (CSR)"
            CLIENT["Browser React (Hydrate)"]:::ui
            ApiProv["ApolloProvider"]:::service
            AuthGuardCL["AuthGuard"]:::service
            ThemeProv["ThemeProvider"]:::service
            click AuthGuardCL "https://github.com/ww-side/structify-frontend/blob/main/src/core/auth/components/auth-guard.tsx"
            click ApiProv "https://github.com/ww-side/structify-frontend/blob/main/src/core/api/apollo-provider.tsx"
            click ThemeProv "https://github.com/ww-side/structify-frontend/blob/main/src/core/theme/components/theme-switcher.tsx"
        end

        %% Presentation Layer
        AppLayer["Presentation Layer"]:::ui
        click AppLayer "https://github.com/ww-side/structify-frontend/tree/main/src/app"

        Layout["Root Layout"]:::ui
        click Layout "https://github.com/ww-side/structify-frontend/blob/main/src/app/layout.tsx"
        Protected["Protected Routes"]:::ui
        click Protected "https://github.com/ww-side/structify-frontend/tree/main/src/app/(protected)"

        %% Widgets
        subgraph "Widgets"
            AuthWidget["Auth Widgets"]:::ui
            click AuthWidget "https://github.com/ww-side/structify-frontend/tree/main/src/widgets/auth"
            HomeWidget["Home Widgets"]:::ui
            click HomeWidget "https://github.com/ww-side/structify-frontend/tree/main/src/widgets/home"
            SettingsWidget["Settings Widgets"]:::ui
            click SettingsWidget "https://github.com/ww-side/structify-frontend/tree/main/src/widgets/settings"
            ViewsWidget["Views Widgets"]:::ui
            click ViewsWidget "https://github.com/ww-side/structify-frontend/tree/main/src/widgets/views"
        end

        %% Feature Modules
        subgraph "Feature Modules"
            Calendar["Calendar Module"]:::ui
            click Calendar "https://github.com/ww-side/structify-frontend/tree/main/src/features/calendar/components"
            Columns["Columns Module"]:::ui
            click Columns "https://github.com/ww-side/structify-frontend/tree/main/src/features/columns/components"
            CreateView["Create-View Module"]:::ui
            click CreateView "https://github.com/ww-side/structify-frontend/tree/main/src/features/create-view/components"
            Rows["Rows Module"]:::ui
            click Rows "https://github.com/ww-side/structify-frontend/tree/main/src/features/rows/services"
            RowVal["Row-Value Module"]:::ui
            click RowVal "https://github.com/ww-side/structify-frontend/tree/main/src/features/row-value/services"
            Sidebar["Sidebar Module"]:::ui
            click Sidebar "https://github.com/ww-side/structify-frontend/tree/main/src/features/sidebar/components"
            ViewMod["View Module"]:::ui
            click ViewMod "https://github.com/ww-side/structify-frontend/tree/main/src/features/view/components"
        end

        %% Shared Utilities & UI Kit
        subgraph "Shared"
            Utils["Utilities"]:::util
            click Utils "https://github.com/ww-side/structify-frontend/tree/main/src/shared/lib"
            UIkit["UI Kit"]:::util
            click UIkit "https://github.com/ww-side/structify-frontend/tree/main/src/shared/ui/kit"
        end

        %% Core Providers & Services
        subgraph "Core"
            AuthServ["Auth Services"]:::service
            click AuthServ "https://github.com/ww-side/structify-frontend/tree/main/src/core/auth/services"
            AuthLib["Auth Schemas"]:::util
            click AuthLib "https://github.com/ww-side/structify-frontend/tree/main/src/core/auth/lib"
            AuthComp["Auth UI Components"]:::service
            click AuthComp "https://github.com/ww-side/structify-frontend/tree/main/src/core/auth/components/auth-form"
            ThemeLib["Theme Context"]:::util
            click ThemeLib "https://github.com/ww-side/structify-frontend/tree/main/src/core/theme/lib"
            UserServ["User Services"]:::service
            click UserServ "https://github.com/ww-side/structify-frontend/tree/main/src/core/user/services"
            UserStore["User Store"]:::service
            click UserStore "https://github.com/ww-side/structify-frontend/blob/main/src/core/user/services/user.store.ts"
            UserLib["User Schemas"]:::util
            click UserLib "https://github.com/ww-side/structify-frontend/tree/main/src/core/user/lib"
        end

        %% Internal Flows
        CLIENT --> Layout
        Layout --> Protected
        Protected --> Calendar & Columns & CreateView & Rows & RowVal & Sidebar & ViewMod
        ApiProv -->|connects to| GraphQL
        SSR --> AuthGuardSS -->|verifies| Protected
        CLIENT --> ApiProv
        CLIENT --> AuthGuardCL
        CLIENT --> ThemeProv
        Calendar & Columns & CreateView & Rows & RowVal & Sidebar & ViewMod --> ApiProv
    end

    %% External Systems
    Browser["User Browser"]:::ext
    Browser -->|HTTP Request| SSR
    SSR -->|GraphQL requests| GraphQL["GraphQL API"]:::external
    GraphQL --> Database["Database"]:::external
    SSR --> AuthExt["Auth Service"]:::external
    Vercel["Vercel Hosting"]:::external
    Vercel --> SSR

    %% Legend / Styles
    classDef ui fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef service fill:#E8F5E9,stroke:#A5D6A7,color:#1B5E20;
    classDef util fill:#ECEFF1,stroke:#B0BEC5,color:#263238;
    classDef external fill:#FFF3E0,stroke:#FFCC80,color:#E65100;
```
