# claudiorivera/scavenger-hunt architecture

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

- Interactive diagram: https://gitdiagram.com/claudiorivera/scavenger-hunt
- Repository: https://github.com/claudiorivera/scavenger-hunt

## Overview

##### Project Type & Purpose
- The project is a full-stack web application built using React, TypeScript, and Next.js. It centers around a virtual scavenger hunt, where a host creates a list of items, and players compete in finding those items under various win conditions.
- The README confirms the use of NextAuth.js for authentication and highlights the interactive, real-time nature of the hunt. There’s also a nod to the “Create T3 Turbo” setup hinting at a monorepo architecture with modern full-stack tooling.

##### Analyzing the File Structure
- The top-level directories include configuration files (like .env.example, package.json, pnpm-workspace.yaml) and the apps folder, which contains the main web application under apps/web. This separation suggests a clear division between the frontend (Next.js specific) and shared packages.
- The apps/web directory shows the typical Next.js structure: a src/app directory that holds pages, API routes (e.g., /api/auth/[...nextauth] and /api/cron-handler), and custom components. Dynamic routes for different hunts (e.g., /hunts/[huntId]) indicate a multi-page, dynamic routing architecture.
- The presence of packages (e.g., packages/auth and packages/db) indicates that authentication logic and database access logic have been abstracted out into separate shared packages. The packages/db directory, in particular, includes a Prisma schema and migrations, reinforcing that Prisma is used as an ORM for managing the database.
- The tooling directories (like tooling/typescript) and configuration files (like turbo.json, vercel.json, .github workflows) suggest an emphasis on CI/CD, shared TypeScript configurations, and streamlined deployment processes.

##### Main Components and Their Relationships
- Client (Frontend): This consists of the Next.js user interface in apps/web. It remotely interacts with the backend APIs. Components are organized by functionality (e.g., hunts, admin, profile).
- Backend (Server/API): Standalone API endpoints are defined within the Next.js application (e.g., authentication endpoints under /api/auth and cron jobs under /api/cron-handler). The app routing and dynamic page structures manage the content for hunts, items, and interactions during a game.
- Authentication Service: Managed through NextAuth.js endpoints, possibly with custom logic abstracted into packages/auth.
- Database: The database is handled via Prisma within packages/db. Migrations and seeding logic are included, signifying an ORM-managed persistence layer.
- Shared Packages: There are shared modules (auth, db) designed for reuse, ensuring that the frontend and backend refer to common logic. This separation increases modularity and maintainability.
- CI/CD and Deployment: Configurations (in .github/workflows, vercel.json, etc.) manage continuous integration and deployment pipelines likely targeting Vercel or a similar platform.

##### Architectural Patterns & Design Principles
- Monorepo Structure: The project uses a monorepo (pnpm-workspace) to manage multiple packages and apps together. This encourages code reuse (authentication, database logic) and consistency across the project.
- Component-Based UI: The React/Next.js application is built using a component-driven design, with organized directories for shared UI components and domain-specific components.
- API Routes as Controller Layer: Next.js API routes act as the controller/handler layer, bridging frontend requests to the authentication and database services.
- Modularization & Separation of Concerns: Clear directory separation (e.g., apps for UI and packages for business logic) adheres to the separation of concerns principle.
- CI/CD & Automated Deployment: The existence of GitHub workflows, Renovate configs, and deployment scripts encourages continuous integration and delivery, automating tests, migrations, and deployments.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Frontend (Next.js Application)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BE["API Gateway/Backend (Next.js API Routes)"]:::backend
        Auth["Authentication Endpoint (NextAuth.js)"]:::auth
        Cron["Cron Handler Endpoint"]:::backend
    end

    %% Shared Packages
    subgraph "Shared Packages"
        AuthShared["Authentication Shared Logic"]:::shared
        DBShared["Database Shared Logic"]:::shared
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database (Prisma ORM & Migrations)"]:::database
        Schema["Prisma Schema"]:::database
    end

    %% CI/CD & Deployment Infrastructure
    subgraph "CI/CD & Deployment"
        CI["GitHub Workflows"]:::cicd
        Vercel["Deployment: vercel.json"]:::cicd
        Turbo["Deployment: turbo.json"]:::cicd
    end

    %% Connections between layers
    FE -->|"APIRequest"| BE
    BE -->|"AuthCall"| Auth
    BE -->|"CronTrigger"| Cron
    BE -->|"DBQuery"| DB
    DB -->|"HasSchema"| Schema
    Auth -->|"UsesSharedLogic"| AuthShared
    DB -->|"ManagedBy"| DBShared

    %% CI/CD interactions
    FE ---|"Triggers"| CI
    BE ---|"Triggers"| CI
    DB ---|"Triggers"| CI
    CI -->|"DeploysTo"| Vercel
    CI -->|"DeploysTo"| Turbo

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef auth fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef shared fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef database fill:#d1ecf1,stroke:#17a2b8,stroke-width:2px;
    classDef cicd fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/claudiorivera/scavenger-hunt/tree/main/apps/web"
    click BE "https://github.com/claudiorivera/scavenger-hunt/tree/main/apps/web/src/app/api"
    click Auth "https://github.com/claudiorivera/scavenger-hunt/blob/main/apps/web/src/app/api/auth/[...nextauth]"
    click AuthShared "https://github.com/claudiorivera/scavenger-hunt/tree/main/packages/auth"
    click DB "https://github.com/claudiorivera/scavenger-hunt/tree/main/packages/db"
    click Schema "https://github.com/claudiorivera/scavenger-hunt/blob/main/packages/db/prisma/schema.prisma"
    click DBShared "https://github.com/claudiorivera/scavenger-hunt/tree/main/packages/db"
    click CI "https://github.com/claudiorivera/scavenger-hunt/tree/main/.github/workflows"
    click Vercel "https://github.com/claudiorivera/scavenger-hunt/blob/main/vercel.json"
    click Turbo "https://github.com/claudiorivera/scavenger-hunt/blob/main/turbo.json"
```
