# hackclub/high-seas architecture

> Architecture diagram of the GitHub repository hackclub/high-seas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hackclub/high-seas
- Repository: https://github.com/hackclub/high-seas

## Overview

##### Main Components

a. Frontend Layer:
- Next.js Application (src/app directory structure)
- Marketing Pages (/marketing)
- Harbor Section (main application area)
- UI Components Library (/components)

b. Backend Layer:
- API Routes (/api)
- Authentication System
- Background Jobs System
- External Services Integration

c. Data Storage:
- Redis (indicated by redis-lock.ts)
- Airtable Integration
- Local Storage (for client-side state)

##### Client-Side Architecture
- Route-based pages using Next.js App Router
- Component hierarchy
- State management
- UI/UX elements (including audio feedback)

##### Server-Side Architecture
- API endpoints structure
- Cron jobs system
- Background processing
- External integrations

##### Specific Implementation Details

**[Client Layer]**
- Marketing Site
- Harbor Dashboard
- Battles System
- Gallery
- Shipyard
- Shop
- Signpost
- UI Components

**[Server Layer]**
- API Routes
- Admin Controls
- Battle System
- Shop Management
- Stats Generation
- Background Jobs
- Daily Tasks
- Minute-level Tasks
- External Integrations
- Slack
- Airtable
- WakaTime
- Sentry

**[Data Layer]**
- Redis Cache
- Airtable Database
- Local Storage

##### Flow Representations

- User authentication flow
- Data flow between frontend and backend
- Integration points with external services
- Background job processing flow

##### Additional Elements

Include:
- Error handling flow (Sentry integration)
- Authentication boundaries
- Cache layers
- API rate limiting
- Background job scheduling

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Marketing["Marketing Site"]:::frontend
        Harbor["Harbor Dashboard"]:::frontend
        UIComponents["UI Components"]:::frontend
        
        subgraph HarborFeatures
            Battles["Battles Interface"]:::frontend
            Gallery["Gallery"]:::frontend
            Shipyard["Shipyard"]:::frontend
            Shop["Shop Interface"]:::frontend
            Signpost["Signpost"]:::frontend
        end
        
        Harbor --> HarborFeatures
    end
    
    subgraph Server
        API["API Routes"]:::backend
        
        subgraph APIEndpoints
            AdminAPI["Admin Controls"]:::api
            BattleAPI["Battle System"]:::api
            ShopAPI["Shop Management"]:::api
            StatsAPI["Stats Generation"]:::api
        end
        
        subgraph BackgroundJobs
            DailyTasks["Daily Tasks"]:::job
            MinuteTasks["Minute Tasks"]:::job
        end
        
        subgraph Auth
            AuthSystem["Authentication System"]:::auth
        end
        
        API --> APIEndpoints
    end
    
    subgraph ExternalServices
        Slack["Slack Integration"]:::external
        Airtable["Airtable Integration"]:::external
        WakaTime["WakaTime Integration"]:::external
        Sentry["Sentry Integration"]:::external
    end
    
    subgraph Storage
        Redis["Redis Cache"]:::storage
        AirtableDB["Airtable Database"]:::storage
        LocalStorage["Local Storage"]:::storage
    end
    
    %% Connections
    HarborFeatures --> API
    API --> ExternalServices
    API --> Storage
    BackgroundJobs --> Storage
    AuthSystem --> API
    
    %% Click Events
    click Marketing "https://github.com/hackclub/high-seas/tree/main/src/app/marketing"
    click Harbor "https://github.com/hackclub/high-seas/tree/main/src/app/harbor"
    click UIComponents "https://github.com/hackclub/high-seas/tree/main/src/components/ui"
    click API "https://github.com/hackclub/high-seas/tree/main/src/app/api"
    click AuthSystem "https://github.com/hackclub/high-seas/blob/main/src/app/utils/auth.ts"
    click BackgroundJobs "https://github.com/hackclub/high-seas/tree/main/src/app/api/cron"
    click Battles "https://github.com/hackclub/high-seas/tree/main/src/app/harbor/battles"
    click BattleAPI "https://github.com/hackclub/high-seas/tree/main/src/app/api/battles"
    click Shop "https://github.com/hackclub/high-seas/tree/main/src/app/harbor/shop"
    click ShopAPI "https://github.com/hackclub/high-seas/tree/main/src/app/api/buy"
    click Redis "https://github.com/hackclub/high-seas/blob/main/lib/redis-lock.ts"
    click Airtable "https://github.com/hackclub/high-seas/blob/main/src/app/utils/airtable.ts"
    click WakaTime "https://github.com/hackclub/high-seas/blob/main/src/app/utils/waka.ts"
    click Sentry "https://github.com/hackclub/high-seas/blob/main/sentry.client.config.ts"
    click Slack "https://github.com/hackclub/high-seas/tree/main/src/app/api/slack_redirect"
    click Shipyard "https://github.com/hackclub/high-seas/tree/main/src/app/harbor/shipyard"
    click Gallery "https://github.com/hackclub/high-seas/tree/main/src/app/harbor/gallery"
    
    %% Styles
    classDef frontend fill:#2196F3,color:white
    classDef backend fill:#4CAF50,color:white
    classDef api fill:#81C784,color:white
    classDef job fill:#FF9800,color:white
    classDef auth fill:#F44336,color:white
    classDef external fill:#FFC107,color:black
    classDef storage fill:#9C27B0,color:white
    
    %% Legend
    subgraph Legend
        Frontend["Frontend Component"]:::frontend
        Backend["Backend Service"]:::backend
        APIRoute["API Route"]:::api
        Job["Background Job"]:::job
        AuthComp["Auth Component"]:::auth
        ExtService["External Service"]:::external
        DataStorage["Data Storage"]:::storage
    end
```
