# hack-psu/check-in architecture

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

- Interactive diagram: https://gitdiagram.com/hack-psu/check-in
- Repository: https://github.com/hack-psu/check-in

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (app router) and React.
- It delegates authentication and data storage to Firebase and consumes various domain-specific REST endpoints via a custom API client.

##### File Structure
- src/app — Next.js pages and layouts (React UI entry points).
- app/layout.tsx sets up global layout and providers.
- Sub-directories (auth, judging, scan, manual, etc.) each expose a page.tsx.
- src/common
- /config — environment & Firebase initialization.
- /context — React context providers (AuthGuard, FirebaseProvider, LayoutProvider).
- /api — domain-specific modules (analytics, event, hackathon, judging, scan, etc.). Each has entity.ts, hook.ts (React hooks), provider.ts, and index.ts exports.
- /types — shared TypeScript types.
- src/components — shared UI pieces (e.g. BottomNavbar).
- src/lib — utility functions.
- Configuration files (.eslintrc.json, next.config.js, tailwind.config.ts, etc.) orchestrate build, linting, styling.

##### README
- Confirms a Next.js app bootstrapped via create-next-app.
- Mentions font optimization, dev scripts, Vercel for deployment.
- No in-repo backend; data is fetched via the API client to external services (likely a separate REST API or Firebase).

##### Main Components
a. Client Browser (User)
b. Next.js Frontend
- Pages & Layouts (React components under src/app)
- Shared Components & Utilities (src/components, src/lib)
- Context Providers (AuthGuard, FirebaseProvider)
- API Client Layer (src/common/api/*)
c. External Services
- Firebase (Authentication, Firestore/Realtime DB)
- External REST API(s) for analytics, events, judging, etc.
- Vercel CDN/Hosting
d. Data Flow & Interactions
- HTTP(S) requests from client → Next.js serverless functions (if any) or directly to external APIs.
- Auth flows via Firebase SDK.
- Static asset serving via Vercel CDN.

##### Architectural Patterns & Design Principles
- Component-based UI (React).
- Single unified layout wrapping nested pages (Next.js app router).
- Context-based dependency injection (AuthGuard ensures protected routes; FirebaseProvider initializes SDK).
- Modular API layer: each domain area has its own provider, hook, and entity definitions.
- Separation of concerns: UI (src/app + src/components), business/data logic (src/common/api + src/common/context), configuration (src/common/config).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["User Browser"]:::external
        Vercel["Vercel CDN/Hosting"]:::external
        Browser -->|fetch HTML/JS| Vercel

        subgraph "Next.js Frontend" 
            direction TB
            Layout["Page: Layout"]:::ui
            Globals["Styles: globals.css"]:::ui
            RootPage["Page: / (page.tsx)"]:::ui
            AuthPage["Page: /auth"]:::ui
            JudgingPage["Page: /judging"]:::ui
            ManualPage["Page: /manual"]:::ui
            ScanPage["Page: /scan"]:::ui
            NotFound["Page: NotFound"]:::ui
            BottomNav["Component: BottomNavbar"]:::ui
            Utils["Utils: utils.ts"]:::ui

            Vercel -->|serve| Layout
            Layout --> Globals
            Layout --> BottomNav
            Layout --> RootPage
            Layout --> AuthPage
            Layout --> JudgingPage
            Layout --> ManualPage
            Layout --> ScanPage
            Layout --> NotFound
            RootPage --> Utils
        end
    end

    %% Client Logic Layer
    subgraph "Client Logic Layer"
        direction TB
        subgraph "Configuration & Contexts"
            direction TB
            EnvConfig["Config: environment.ts"]:::config
            FirebaseConfig["Config: firebase.ts"]:::config
            ConfigIndex["Config Index"]:::config
            AuthGuard["Context: AuthGuard"]:::context
            FirebaseProv["Context: FirebaseProvider"]:::context
            LayoutProv["Context: LayoutProvider"]:::context
            ContextIndex["Context Index"]:::context

            EnvConfig --> FirebaseConfig --> ConfigIndex
            FirebaseConfig --> FirebaseProv
            AuthGuard --> ContextIndex
            FirebaseProv --> ContextIndex
            LayoutProv --> ContextIndex
        end

        subgraph "API Client & Modules"
            direction TB
            APIClient["API Client Core"]:::api
            AnalyticsMod["API Module: analytics"]:::api
            EventMod["API Module: event"]:::api
            HackathonMod["API Module: hackathon"]:::api
            JudgingMod["API Module: judging"]:::api
            ScanMod["API Module: scan"]:::api

            APIClient --> AnalyticsMod
            APIClient --> EventMod
            APIClient --> HackathonMod
            APIClient --> JudgingMod
            APIClient --> ScanMod
        end

        %% Integration
        Layout --> AuthGuard
        Layout --> FirebaseProv
        Layout --> LayoutProv
        BottomNav --> AuthGuard
        Utils --> APIClient
        AuthGuard --> APIClient
    end

    %% External Services Layer
    subgraph "External Services Layer"
        direction TB
        FirebaseService["Firebase Auth/Database"]:::external
        RESTAPIs["External REST APIs"]:::external
    end

    %% Data Flows
    APIClient -->|REST calls| RESTAPIs
    FirebaseProv -->|init SDK| FirebaseService

    %% Click Events
    click Layout "https://github.com/hack-psu/check-in/blob/main/src/app/layout.tsx"
    click Globals "https://github.com/hack-psu/check-in/blob/main/src/app/globals.css"
    click RootPage "https://github.com/hack-psu/check-in/blob/main/src/app/page.tsx"
    click AuthPage "https://github.com/hack-psu/check-in/blob/main/src/app/auth/page.tsx"
    click JudgingPage "https://github.com/hack-psu/check-in/blob/main/src/app/judging/page.tsx"
    click ManualPage "https://github.com/hack-psu/check-in/blob/main/src/app/manual/page.tsx"
    click ScanPage "https://github.com/hack-psu/check-in/blob/main/src/app/scan/page.tsx"
    click NotFound "https://github.com/hack-psu/check-in/blob/main/src/app/not-found.tsx"
    click BottomNav "https://github.com/hack-psu/check-in/blob/main/src/components/BottomNavbar.tsx"
    click Utils "https://github.com/hack-psu/check-in/blob/main/src/lib/utils.ts"
    click APIClient "https://github.com/hack-psu/check-in/blob/main/src/common/api/apiClient.ts"
    click AnalyticsMod "https://github.com/hack-psu/check-in/blob/main/src/common/api/analytics/index.ts"
    click EventMod "https://github.com/hack-psu/check-in/blob/main/src/common/api/event/index.ts"
    click HackathonMod "https://github.com/hack-psu/check-in/blob/main/src/common/api/hackathon/index.ts"
    click JudgingMod "https://github.com/hack-psu/check-in/blob/main/src/common/api/judging/index.ts"
    click ScanMod "https://github.com/hack-psu/check-in/blob/main/src/common/api/scan/index.ts"
    click FirebaseConfig "https://github.com/hack-psu/check-in/blob/main/src/common/config/firebase.ts"
    click EnvConfig "https://github.com/hack-psu/check-in/blob/main/src/common/config/environment.ts"
    click ConfigIndex "https://github.com/hack-psu/check-in/blob/main/src/common/config/index.ts"
    click AuthGuard "https://github.com/hack-psu/check-in/blob/main/src/common/context/AuthGuard.tsx"
    click FirebaseProv "https://github.com/hack-psu/check-in/blob/main/src/common/context/FirebaseProvider.tsx"
    click LayoutProv "https://github.com/hack-psu/check-in/blob/main/src/common/context/LayoutProvider.tsx"
    click ContextIndex "https://github.com/hack-psu/check-in/blob/main/src/common/context/index.ts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef config fill:#E6FFEA,stroke:#22863A,color:#22863A;
    classDef context fill:#EBF5FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#FFE8D6,stroke:#D73A49,color:#D73A49;
    classDef external fill:#F0F0F0,stroke:#666666,color:#333333;
```
