# suceavahacks/hackacode architecture

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

- Interactive diagram: https://gitdiagram.com/suceavahacks/hackacode
- Repository: https://github.com/suceavahacks/hackacode

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router) named “Hackacode.”
- It delivers coding challenge pages, user authentication, and CRUD operations on challenges via a Supabase backend.

##### File structure
- app/ → Next.js App Router directory containing page.tsx, layout.tsx, route.ts files for server-side and client-side rendering.
- components/ → reusable React UI pieces (Navbar, Sidebar, TestCase, etc.).
- utils/ → data-access layer: mutations/queries for user and problem operations, Supabase client and server wrappers.
- schemas/ → TypeScript schemas for validation (problemSchema.ts).
- public/ → static assets and SVG components.
- config files → tailwind.config.ts, next.config.ts, Dockerfile for styling, build, deployment setups.

##### README
- Minimal content (“Houdy! This is Hackacode!”), so we infer from file names that the core flows are:
- User signup/sign-in via OAuth (GitHub, Google, Slack)
- Protected pages for creating/publishing coding challenges
- Viewing and running test cases on challenges

a. Main components
- Client (Browser)
- Next.js Frontend (React Client Components + Server Components)
- Next.js API Routes / Server Actions (app/auth/callback/route.ts, utils/mutations, utils/queries)
- Supabase Services
– Auth (OAuth providers)
– PostgreSQL Database (problems, users, test cases)
– Storage (if used)
- CDN / Static Asset Hosting (public/ folder)

b. Relationships & data flow
1. Browser requests a page (SSR or SSG) → Next.js Server
2. Next.js Server renders the page, calling Supabase Server library for data fetch
3. Client Components invoke frontend utils/mutations or utils/queries → Next.js API routes or direct Supabase client calls
4. Supabase Auth handles OAuth flows → issues JWT → Next.js middleware.ts validates auth on protected routes
5. Supabase Database returns/query results → Next.js sends JSON responses → Browser updates UI

c. Architectural patterns & design principles
- Next.js App Router separation of Server Components vs Client Components
- Middleware layer for auth enforcement (middleware.ts + utils/supabase/middleware)
- Layered data-access: high-level mutations/queries modules wrap low-level Supabase calls
- Clear separation of concerns: UI (components/), business logic (utils/), data schemas (schemas/)

d. Key technologies & frameworks
- Next.js (React, SSR/SSG, App Router)
- React + Tailwind CSS for styling
- Supabase (Auth, Database, optional Storage)
- TypeScript for type safety
- Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        Browser["Browser"]:::external
        CDN["CDN / Static Assets"]:::frontend
        subgraph "Next.js Server"
            direction TB
            SSR["App Router (Pages & Layout)"]:::frontend
            API["Next.js API Routes & Server Actions"]:::api
        end
        subgraph "React UI Components"
            direction TB
            Navbar["Navbar"]:::frontend
            Sidebar["Sidebar"]:::frontend
            TestCase["Test Case Renderer"]:::frontend
            Avatar["Avatar"]:::frontend
            Footer["Footer"]:::frontend
            Loading["Loading Indicator"]:::frontend
        end
        Browser -->|HTTP GET/POST| SSR
        Browser -->|Access Static Assets| CDN
        Browser -->|Interacts| Navbar
        Browser -->|Interacts| Sidebar
        Browser -->|Interacts| TestCase
        Browser -->|Interacts| Avatar
        Browser -->|Interacts| Footer
        Browser -->|Interacts| Loading
        SSR -->|"calls"| API
    end

    %% Data Access Layer
    subgraph "Data Access Layer" 
        direction TB
        Mutations["Mutations"]:::api
        Queries["Queries"]:::api
        Schemas["Validation Schemas"]:::data
    end

    API -->|uses| Mutations
    API -->|uses| Queries
    Mutations -->|validates via| Schemas

    %% Supabase Services
    subgraph "Supabase Services" 
        direction TB
        Auth["Auth Service (OAuth)"]:::external
        DB["PostgreSQL Database"]:::data
    end

    API -->|Auth calls| Auth
    API -->|DB queries| DB
    Mutations -->|DB writes/reads| DB
    Queries -->|DB reads| DB
    Auth -->|stores user| DB

    %% External OAuth Providers
    subgraph "OAuth Providers" 
        direction TB
        GitHub["GitHub"]:::external
        Google["Google"]:::external
        Slack["Slack"]:::external
    end

    GitHub -->|OAuth flow| Auth
    Google -->|OAuth flow| Auth
    Slack -->|OAuth flow| Auth

    %% Click Events
    click SSR "https://github.com/suceavahacks/hackacode/blob/main/app/layout.tsx"
    click SSR "https://github.com/suceavahacks/hackacode/blob/main/app/page.tsx"
    click SSR "https://github.com/suceavahacks/hackacode/blob/main/app/not-found.tsx"
    click SSR "https://github.com/suceavahacks/hackacode/blob/main/app/globals.css"
    click API "https://github.com/suceavahacks/hackacode/blob/main/app/auth/callback/route.ts"
    click Browser "https://github.com/suceavahacks/hackacode/blob/main/app/signup/page.tsx"
    click Browser "https://github.com/suceavahacks/hackacode/blob/main/app/signin/page.tsx"
    click Browser "https://github.com/suceavahacks/hackacode/blob/main/app/logout/page.tsx"
    click Browser "https://github.com/suceavahacks/hackacode/blob/main/app/challenges/publish/page.tsx"
    click Browser "https://github.com/suceavahacks/hackacode/blob/main/app/settings/page.tsx"
    click CDN "https://github.com/suceavahacks/hackacode/blob/main/app/json/1.json"
    click Navbar "https://github.com/suceavahacks/hackacode/blob/main/components/Navbar.tsx"
    click Sidebar "https://github.com/suceavahacks/hackacode/blob/main/components/Sidebar.tsx"
    click TestCase "https://github.com/suceavahacks/hackacode/blob/main/components/TestCase.tsx"
    click Avatar "https://github.com/suceavahacks/hackacode/blob/main/components/Avatar.tsx"
    click Footer "https://github.com/suceavahacks/hackacode/blob/main/components/Footer.tsx"
    click Loading "https://github.com/suceavahacks/hackacode/blob/main/components/Loading.tsx"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/supabase/client.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/supabase/server.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/supabase/middleware.ts"
    click API "https://github.com/suceavahacks/hackacode/blob/main/middleware.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/problems/publish.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/user/oauth/githubAuth.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/user/oauth/googleAuth.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/user/oauth/slackAuth.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/user/signup.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/mutations/user/signin.ts"
    click Queries "https://github.com/suceavahacks/hackacode/blob/main/utils/queries/user/getUser.ts"
    click Schemas "https://github.com/suceavahacks/hackacode/blob/main/schemas/problemSchema.ts"
    click CDN "https://github.com/suceavahacks/hackacode/tree/main/public/"
    click CDN "https://github.com/suceavahacks/hackacode/tree/main/public/app/svg"
    click CDN "https://github.com/suceavahacks/hackacode/tree/main/public/home/svgs"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/lib/utils.ts"
    click Mutations "https://github.com/suceavahacks/hackacode/blob/main/utils/utils.ts"
    click CDN "https://github.com/suceavahacks/hackacode/blob/main/next.config.ts"
    click CDN "https://github.com/suceavahacks/hackacode/blob/main/tailwind.config.ts"
    click CDN "https://github.com/suceavahacks/hackacode/tree/main/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E6FBD,stroke-width:1px
    classDef api fill:#DFFFE0,stroke:#3C9D20,stroke-width:1px
    classDef data fill:#FFE4B3,stroke:#CC8400,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#666666,stroke-width:1px
```
