# forkidd214/echo-apply architecture

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

- Interactive diagram: https://gitdiagram.com/forkidd214/echo-apply
- Repository: https://github.com/forkidd214/echo-apply

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (app directory + React), focused on dynamic form building, management (admin), and public form publishing.
- It uses Supabase for authentication, database (PostgreSQL), and possibly storage; it also contains a JSON-server helper for local/dev purposes.

##### File Structure Analysis
- Top-level config: next.config.mjs, tsconfig.json, tailwind.config.ts, ESLint/Prettier configs.
- src/app: Next.js app-router pages and layouts – routes for login, auth callbacks, account management, workspace (admin dashboard), form builder (admin create, share, result), and public publish views.
- src/components: reusable React UI and domain controls (blocks, navigation, buttons, carousels).
- src/lib & src/utils: React context/providers (React Query, Supabase client), custom hooks (use-form, use-block), supabase server/client wrappers, JSON-server fallback, type definitions.
- supabase/: local CLI configuration, migrations, and seed scripts for PostgreSQL schema.

##### Key Architectural Patterns
- Frontend: Next.js with server-components and client-components, folder-based routing composing layouts for admin vs. public flows.
- Data layer: React Query for client-side data fetching, combined with Supabase client on the browser and server-side helpers for SSR/API routes.
- Backend: Supabase handles auth (login/logout/confirm), storage, and database. Custom middleware wraps Next.js requests to verify session.
- Development: JSON-server used in utils/json-server.ts for mocking API in dev mode if Supabase is not available.

a. Main Components
- Client (Browser): React/Next.js rendered UI, React Query hooks, Supabase JS client.
- Next.js Server: SSR and API routing layer, React server components, middleware (auth verification).
- Supabase Services:
- Auth service (signup, login, confirmation)
- Postgres DB (forms, blocks, users, results)
- Storage (if used for block thumbnails or assets)
- Remote Schema (GraphQL if configured)
- Dev Mock (JSON-server): optional local API fallback.
- Deployment Platform (e.g., Vercel): hosts Next.js, environment variables, built artifacts.

b. Relationships and Data Flows
1. Browser requests page → Next.js Server
2. Next.js SSR or RSC fetches data via:
– Supabase client (browser) for client-side queries;
– Supabase server helper (server) for SSR/API calls.
3. Supabase Auth verifies JWT session, returns auth state to Next.js middleware.
4. Postgres holds form schemas, block definitions, user accounts, results.
5. React Query caches & manages remote data, updates UI.
6. JSON-server intercepts calls when running in local/mock mode.

c. Architectural Patterns & Principles
- Separation of Concerns: UI components vs. data hooks vs. providers vs. server helpers.
- Provider pattern: react-query-provider + supabase provider wrap entire app.
- Folder-based routing enforces clear Admin vs. Public layouts.
- Migration-driven DB evolution ensures consistency between code and database schema.

d. Key Technologies
- Next.js (app router, server & client components)
- React Query (data fetching & caching)
- Supabase (Auth, Postgres, storage, GraphQL remote schema)
- Tailwind CSS (styling)
- pnpm (package management)
- JSON-server (local mocking)

##### Final Recommendations
- React Query layer between Browser and all data sources.
- Environment-specific paths (dev vs. prod).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Layer
    subgraph "Browser (Next.js Client)"
        direction TB
        UI["React UI"]:::frontend
        RQ["React Query"]:::frontend
        SI["Supabase JS Client"]:::frontend
        Hooks["Custom Hooks & Context"]:::frontend
        UIComponents["UI Components Library"]:::frontend
    end

    %% Deployment & Server Layer
    subgraph "Vercel Deployment"
        direction TB
        subgraph "Next.js Server"
            direction TB
            SC["Server Components & Routing"]:::server
            API["API Routes & Middleware"]:::server
            SSH["Supabase Server Helper"]:::server
            Layout["Global Layout & Styling"]:::server
            AuthPages["Authentication Pages & Routes"]:::server
            Account["Account Management"]:::server
            Workspace["Admin Dashboard (Workspace)"]:::server
            FormBuilder["Form Builder (Admin)"]:::server
            Publish["Public Form Publish"]:::server
            Providers["React Query & Supabase Providers"]:::server
            Middleware["Next.js Middleware (Auth Verification)"]:::server
        end
    end

    %% Supabase Services
    subgraph "Supabase" 
        direction TB
        Auth["Auth Service"]:::db
        PG["Postgres DB (forms, blocks, users, results)"]:::db
        Stor["Storage"]:::db
        GQL["GraphQL Remote Schema"]:::db
    end

    %% Dev Mock
    JSON["JSON-server (Dev)"]:::dev

    %% Data Flows
    UI -->|"renders via"| RQ
    RQ -->|"client queries"| SI
    SI -->|"calls Auth, CRUD"| Auth & PG
    UI -->|"page/API request"| SC
    SC -->|"routes & SSR"| API
    API -->|"verifies session"| Auth
    API -->|"reads/writes"| PG
    API -->|"returns data"| SC
    SC -->|"renders HTML"| UI
    SC -->|"server queries"| SSH
    SSH -->|"auth check & CRUD"| Auth & PG
    RQ -->|"updates UI"| UI
    JSON -->|"fallback API (dev)"| API

    %% Click Events
    click UIComponents "https://github.com/forkidd214/echo-apply/tree/main/src/components"
    click Hooks "https://github.com/forkidd214/echo-apply/blob/main/src/lib/use-form.ts"
    click Hooks "https://github.com/forkidd214/echo-apply/blob/main/src/lib/use-block.ts"
    click Hooks "https://github.com/forkidd214/echo-apply/blob/main/src/lib/form-context.tsx"
    click SC "https://github.com/forkidd214/echo-apply/tree/main/src/app"
    click Workspace "https://github.com/forkidd214/echo-apply/tree/main/src/app/workspace"
    click FormBuilder "https://github.com/forkidd214/echo-apply/tree/main/src/app/form/[slug]/(admin)"
    click Publish "https://github.com/forkidd214/echo-apply/tree/main/src/app/form/[slug]/(publish)"
    click AuthPages "https://github.com/forkidd214/echo-apply/tree/main/src/app/login"
    click AuthPages "https://github.com/forkidd214/echo-apply/blob/main/src/app/auth/confirm/route.ts"
    click AuthPages "https://github.com/forkidd214/echo-apply/blob/main/src/app/auth/logout/route.ts"
    click Account "https://github.com/forkidd214/echo-apply/tree/main/src/app/account"
    click Layout "https://github.com/forkidd214/echo-apply/blob/main/src/app/layout.tsx"
    click Providers "https://github.com/forkidd214/echo-apply/tree/main/src/app/_providers"
    click Middleware "https://github.com/forkidd214/echo-apply/blob/main/src/middleware.ts"
    click SSH "https://github.com/forkidd214/echo-apply/blob/main/src/utils/supabase/server.ts"
    click SI "https://github.com/forkidd214/echo-apply/blob/main/src/utils/supabase/client.ts"
    click JSON "https://github.com/forkidd214/echo-apply/blob/main/src/utils/json-server.ts"
    click Auth "https://github.com/forkidd214/echo-apply/blob/main/supabase/config.toml"
    click PG "https://github.com/forkidd214/echo-apply/blob/main/supabase/migrations/*.sql"
    click PG "https://github.com/forkidd214/echo-apply/blob/main/supabase/seed.sql"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef server fill:#DFFFE0,stroke:#228B22,stroke-width:1px
    classDef db fill:#FFE8CC,stroke:#FF8C00,stroke-width:1px
    classDef dev fill:#E0E0E0,stroke:#666666,stroke-width:1px
```
