# marsx-dev/devhunt architecture

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

- Interactive diagram: https://gitdiagram.com/marsx-dev/devhunt
- Repository: https://github.com/marsx-dev/devhunt

## Overview

##### Project Type & Purpose
- This is a full-stack web application built with Next.js (using the App Router) that serves as a collaborative launching platform for developer tools.
- Core responsibilities:
- Render marketing, blog, tool listing, and user-account pages (SSG/SSR/ISR).
- Expose internal API routes (`app/api` and `pages/api`) for actions like login, newsletter signup, comment/upvote notifications, Product Hunt integrations, and ChatGPT.
- Persist data (users, tools, comments, upvotes, etc.) in a Supabase PostgreSQL backend, use Supabase Auth for login (incl. social OAuth), and Supabase Storage/File Upload.

##### File Structure & Architectural Patterns
- Top-level “app” folder: React server- and client-components following Next.js App Router conventions; directory-based routing for pages and API endpoints under `app/api/*/route.ts`.
- Legacy `/pages/api`: additional REST/edge functions.
- `components/` + `components/ui/`: reusable, atomic UI building blocks, following a component-library pattern.
- `utils/supabase/services`: a thin service layer encapsulating direct Supabase SDK calls (BaseDbService, CacheService, domain services).
- `supabase/`: dump.sql and config for local DB restore.
- `middleware.ts`, `next.config.js`, `tailwind.config.js`: app-wide policies, build and styling configuration.

##### Key Architectural Elements
a. Frontend (Next.js App)
- React Server Components handle SSR/SSG where possible.
- Client Components handle interactivity (commenting, upvoting, form submission) using Supabase JS client via React context provider.
- Styling via Tailwind CSS; global CSS in `app/globals.css`.
b. API Layer
- Internal API Routes:
- Under `app/api/*/route.ts` for backend logic (runs server-side).
- Under `pages/api` for supplemental endpoints (ChatGPT proxy, legacy support).
- Services invoked by these routes reside in `utils/supabase/services/*`.
c. Database & Auth Backend (Supabase)
- PostgreSQL database (tables for users, tools, comments, upvotes, etc.).
- Auth system with Social OAuth (GitHub, Google).
- Storage buckets for images and assets uploaded via UI.
d. External Integrations
- Product Hunt API (`ph-dev-tools` route).
- ChatGPT via `pages/api/chat-gpt.ts`.
- Newsletter service via internal API.
e. Hosting & Deployment
- Vercel for frontend & serverless functions.
- Environment variables (`NEXT_PUBLIC_SUPABASE_URL`, `ANON_KEY`, `SERVICE_ROLE_KEY`).

1. Client Browser
2. Next.js Frontend (Vercel Edge / Serverless)
– App Router pages (React Server/Client components)
– API Routes (`app/api` & `pages/api`)
3. Supabase Backend
– Auth
– PostgreSQL DB
– Storage
– Realtime listeners (for notifications)
4. External Services
– OAuth Providers (GitHub, Google)
– Product Hunt API
– OpenAI (ChatGPT)
– Newsletter/mail service
5. CI/CD & Hosting (Vercel)
b. Relationships & Data Flow
- Browser ←→ Next.js pages (HTTP/HTTPS)
- Next.js pages/Client components ←→ Supabase JS SDK (via React provider)
- Next.js API routes → Supabase Admin SDK (server-side calls, service role)
- Next.js API routes → External APIs (Product Hunt, ChatGPT)
- Supabase triggers/webhooks → Next.js notification routes (optional)
c. Architectural Patterns
- Server-Side Rendering & Static Generation
- Client-Side Rendering for interactive widgets
- “Service Layer” pattern isolating database calls
- Atomic Design in UI (component library)
- BaaS (Backend-as-a-Service) with Supabase
d. Technology Labels
- Next.js (App Router)
- React Server/Client Components
- Supabase (Auth, Postgres, Storage, Realtime)
- Tailwind CSS
- Vercel (Edge Functions / Serverless)
- External OAuth & Third-Party APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        Browser["Client Browser"]:::frontend
        AppRouter["React Server Components\n(App Router)"]:::frontend
        ClientComp["React Client Components"]:::frontend
        subgraph "Internal API Routes (app/api)"
            direction TB
            Login["/api/login"]:::api
            NewsletterAPI["/api/newsletter"]:::api
            CommentNotif["/api/comment-notification"]:::api
            UpvoteNotif["/api/upvote-notification"]:::api
            PHDevTools["/api/ph-dev-tools"]:::api
            TestAPI["/api/test"]:::api
        end
        subgraph "Legacy API Routes (pages/api)"
            direction TB
            PagesAPI["pages/api/"]:::api
            ChatGPT["/api/chat-gpt"]:::api
            WeekTools["/api/week-tools"]:::api
            PastWeek["/api/past-week-tools"]:::api
        end
    end

    %% Supabase Backend
    subgraph "Supabase (BaaS)" 
        direction TB
        Auth[(Auth)]:::supabase
        DB[(PostgreSQL)]:::supabase
        Storage[(Storage)]:::supabase
        Realtime["Realtime Listeners"]:::supabase
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["OAuth Providers\n(GitHub, Google)"]:::external
        PHAPI["Product Hunt API"]:::external
        OpenAI["OpenAI (ChatGPT)"]:::external
        NewsletterSvc["Newsletter/Mail Service"]:::external
    end

    %% Hosting & CI/CD
    subgraph "Hosting & CI/CD"
        direction TB
        Vercel["Vercel\n(Edge & Serverless)"]:::infra
    end

    %% Relationships
    Browser -->|"HTTP/HTTPS"| AppRouter
    AppRouter -->|"renders pages"| ClientComp
    ClientComp -->|"Supabase JS SDK\n(via React Provider)"| Auth
    ClientComp -->|"Supabase JS SDK\n(via React Provider)"| DB
    ClientComp -->|"Supabase JS SDK\n(via React Provider)"| Storage

    Browser -->|"AJAX/API"| Login
    Browser -->|"AJAX/API"| NewsletterAPI
    Browser -->|"AJAX/API"| CommentNotif
    Browser -->|"AJAX/API"| UpvoteNotif
    Browser -->|"AJAX/API"| PHDevTools
    Browser -->|"AJAX/API"| TestAPI
    Browser -->|"AJAX/API"| PagesAPI
    Browser -->|"AJAX/API"| ChatGPT
    Browser -->|"AJAX/API"| WeekTools
    Browser -->|"AJAX/API"| PastWeek

    Login -->|"Admin SDK"| Auth
    NewsletterAPI -->|"Admin SDK"| DB
    CommentNotif --> DB
    UpvoteNotif --> DB
    PHDevTools --> PHAPI
    TestAPI --> Auth

    PagesAPI --> OpenAI
    PagesAPI --> PHAPI

    Auth -->|"OAuth Flow"| OAuth
    Auth --> DB

    Vercel --> AppRouter
    Vercel --> Login
    Vercel --> PagesAPI

    %% Click Events
    click AppRouter "https://github.com/marsx-dev/devhunt/tree/main/app/"
    click Login "https://github.com/marsx-dev/devhunt/blob/main/app/api/login/route.ts"
    click NewsletterAPI "https://github.com/marsx-dev/devhunt/blob/main/app/api/newsletter/route.ts"
    click CommentNotif "https://github.com/marsx-dev/devhunt/blob/main/app/api/comment-notification/route.ts"
    click UpvoteNotif "https://github.com/marsx-dev/devhunt/blob/main/app/api/upvote-notification/route.ts"
    click PHDevTools "https://github.com/marsx-dev/devhunt/blob/main/app/api/ph-dev-tools/route.ts"
    click TestAPI "https://github.com/marsx-dev/devhunt/blob/main/app/api/test/route.ts"
    click PagesAPI "https://github.com/marsx-dev/devhunt/tree/main/pages/api/"
    click ChatGPT "https://github.com/marsx-dev/devhunt/blob/main/pages/api/chat-gpt.ts"
    click WeekTools "https://github.com/marsx-dev/devhunt/blob/main/pages/api/week-tools.ts"
    click PastWeek "https://github.com/marsx-dev/devhunt/blob/main/pages/api/past-week-tools.ts"
    click services "https://github.com/marsx-dev/devhunt/tree/main/utils/supabase/services/"
    click BaseDbService "https://github.com/marsx-dev/devhunt/blob/main/utils/supabase/services/BaseDbService.ts"
    click CacheService "https://github.com/marsx-dev/devhunt/blob/main/utils/supabase/services/CacheService.ts"
    click supabaseClient "https://github.com/marsx-dev/devhunt/blob/main/utils/supabase/services/supabaseClient.ts"
    click Provider "https://github.com/marsx-dev/devhunt/blob/main/components/supabase/provider.tsx"
    click Listener "https://github.com/marsx-dev/devhunt/blob/main/components/supabase/listener.tsx"
    click UI "https://github.com/marsx-dev/devhunt/tree/main/components/"
    click UIlib "https://github.com/marsx-dev/devhunt/tree/main/components/ui/"
    click Globals "https://github.com/marsx-dev/devhunt/blob/main/app/globals.css"
    click Tailwind "https://github.com/marsx-dev/devhunt/blob/main/tailwind.config.js"
    click Middleware "https://github.com/marsx-dev/devhunt/blob/main/middleware.ts"
    click SupabaseConfig "https://github.com/marsx-dev/devhunt/blob/main/supabase/config.toml"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef api fill:#C8E6C9,stroke:#43A047,color:#1B5E20
    classDef supabase fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#FB8C00,color:#E65100
    classDef infra fill:#FFE0B2,stroke:#F57C00,color:#E65100
```
