# idee8/shipfree architecture

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

- Interactive diagram: https://gitdiagram.com/idee8/shipfree
- Repository: https://github.com/idee8/shipfree

## Overview

##### Project Type & Purpose
- ShipFree is a full-stack, SaaS-style web application built with Next.js (using the App Router), Supabase for authentication and Postgres (with Drizzle ORM) or MongoDB as the database, Stripe & LemonSqueezy for payments, and Mailgun for email notifications. It’s delivered via Docker in both development and production modes.

##### File-Structure Analysis
- Top-level directories:
- docker/ (separate dev/prod compose files & Dockerfiles)
- src/ (Next.js app code, custom API routes, UI components, lib, db, utils)
- public/ (static assets)
- config files (next.config.ts, drizzle.config.ts, tailwind.config.ts)
- src/app – the Next.js application (site pages, auth flows, dashboard)
- src/app/api – custom serverless routes for Stripe, LemonSqueezy webhooks, Mailgun integration
- src/lib – wrappers for external services (supabase client/middleware, mailgun)
- src/db – schema.ts & index.ts with Drizzle ORM setup
- docker/dev & docker/prod – multi-service setups (Next.js container, optional Postgres or MongoDB, Portainer)

a. Main Components
- Client Browser / SPA (Next.js React)
- Next.js Server (Node.js, SSR & API routes)
- Database Layer (Supabase-hosted Postgres or self-hosted Postgres/Mongo in Docker)
- Authentication Service (Supabase Auth)
- Payment Gateways (Stripe, LemonSqueezy)
- Email Service (Mailgun)
- Docker Orchestration (Docker Compose, Portainer)

b. Relationships & Data Flows
- Client ↔ Next.js: page requests, API calls (checkout, webhooks, auth)
- Next.js ↔ Supabase Auth: login/register/session validation (via middleware.ts)
- Next.js ↔ Database: CRUD operations via Drizzle ORM (src/db)
- Next.js API Routes ↔ Stripe & LemonSqueezy: redirect to checkout, receive webhooks → update DB → send emails
- Next.js ↔ Mailgun: send transactional emails (via lib/mailgun.ts)
- Docker Compose orchestrates containers: Next.js, DB, Portainer

c. Architectural Patterns & Principles
- Separation of concerns:
- Presentation (components/ui, app/(site))
- Business logic & data access (lib, db, api routes)
- Serverless / Edge functions via Next.js API routes
- Modular configuration via Drizzle config & environment variables
- Containerized micro-services (Next.js, DB)

d. Key Technologies & Libraries
- Next.js (React, App Router)
- TailwindCSS for styling
- Supabase (Auth + Postgres)
- Drizzle ORM (schema.ts + drizzle.config.ts)
- Stripe & LemonSqueezy SDKs (checkout & webhook handlers)
- Mailgun (email notifications)
- Docker & Docker-Compose (multi-stage builds, dev vs. prod)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Client Browser / SPA"]:::frontend
        CheckoutBTN["CheckoutButton"]:::frontend
        LemonBTN["Lemon Checkout Button"]:::frontend
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        NextServer["Next.js Server\n(Node.js, SSR & API routes)"]:::backend
        AuthMiddleware["Auth Middleware"]:::backend
        subgraph "API Routes"
            direction TB
            StripeCheckoutAPI["Stripe Checkout Route"]:::api
            StripeWebhookAPI["Stripe Webhook Route"]:::api
            LemonWebhookAPI["LemonSqueezy Webhook Route"]:::api
            MailgunAPI["Mailgun API Route"]:::api
        end
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        Database["Postgres / MongoDB"]:::datastore
    end

    %% Authentication Service
    subgraph "Authentication Service"
        direction TB
        SupClient["Supabase Client"]:::external
        SupMiddleware["Supabase Middleware"]:::external
        SupServer["Supabase Server"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        StripeService["Stripe API"]:::external
        LemonService["LemonSqueezy API"]:::external
        MailgunService["Mailgun Service"]:::external
    end

    %% Docker Orchestration
    subgraph "Docker Orchestration"
        direction TB
        DevCompose["Dev Compose & Dockerfiles"]:::docker
        ProdCompose["Prod Compose & Dockerfiles"]:::docker
    end

    %% Static Assets & Config
    subgraph "Static Assets & Config"
        direction TB
        Public["public/ (Static Assets)"]:::config
        NextConfig["next.config.ts"]:::config
        DrizzleConfig["drizzle.config.ts"]:::config
        TailwindConfig["tailwind.config.ts"]:::config
        GlobalsCSS["globals.css"]:::config
    end

    %% Relationships
    Browser -->|"requests/pages & API calls"| NextServer
    CheckoutBTN -->|"/api/stripe/checkout"| StripeCheckoutAPI
    LemonBTN -->|"/api/lemonsqueezy/webhook"| LemonWebhookAPI
    NextServer --> AuthMiddleware
    AuthMiddleware --> SupMiddleware
    SupMiddleware --> SupClient
    SupMiddleware --> SupServer
    NextServer --> Database
    StripeCheckoutAPI -->|"redirect to checkout"| StripeService
    StripeService -->|"webhook events"| StripeWebhookAPI
    StripeWebhookAPI --> Database
    StripeWebhookAPI --> MailgunAPI
    LemonWebhookAPI --> LemonService
    LemonWebhookAPI --> Database
    MailgunAPI --> MailgunService
    DevCompose --> NextServer
    DevCompose --> Database
    DevCompose --> Public
    DevCompose -->|"env vars"| NextConfig
    ProdCompose --> NextServer
    ProdCompose --> Database
    ProdCompose --> Public
    ProdCompose -->|"env vars"| NextConfig

    %% Click Events
    click Browser "https://github.com/idee8/shipfree/tree/main/src/app/"
    click Browser "https://github.com/idee8/shipfree/tree/main/src/components/"
    click Browser "https://github.com/idee8/shipfree/tree/main/src/components/ui/"
    click NextServer "https://github.com/idee8/shipfree/blob/main/next.config.ts"
    click AuthMiddleware "https://github.com/idee8/shipfree/blob/main/src/lib/supabase/middleware.ts"
    click SupClient "https://github.com/idee8/shipfree/blob/main/src/lib/supabase/client.ts"
    click SupServer "https://github.com/idee8/shipfree/blob/main/src/lib/supabase/server.ts"
    click StripeCheckoutAPI "https://github.com/idee8/shipfree/blob/main/src/app/api/stripe/checkout/route.ts"
    click StripeWebhookAPI "https://github.com/idee8/shipfree/blob/main/src/app/api/stripe/webhook/route.ts"
    click CheckoutBTN "https://github.com/idee8/shipfree/blob/main/src/components/CheckoutButton.tsx"
    click LemonWebhookAPI "https://github.com/idee8/shipfree/blob/main/src/app/api/lemonsqueezy/webhook/route.ts"
    click LemonBTN "https://github.com/idee8/shipfree/blob/main/src/components/lemon-button.tsx"
    click MailgunAPI "https://github.com/idee8/shipfree/blob/main/src/app/api/mailgun/route.ts"
    click MailgunService "https://github.com/idee8/shipfree/blob/main/src/lib/mailgun.ts"
    click DevCompose "https://github.com/idee8/shipfree/blob/main/docker/dev/docker-compose.yml"
    click DevCompose "https://github.com/idee8/shipfree/tree/main/docker/dev/Dockerfile"
    click DevCompose "https://github.com/idee8/shipfree/blob/main/docker/dev/docker-compose.postgres.yml"
    click DevCompose "https://github.com/idee8/shipfree/blob/main/docker/dev/docker-compose.mongodb.yml"
    click ProdCompose "https://github.com/idee8/shipfree/blob/main/docker/prod/docker-compose.yml"
    click ProdCompose "https://github.com/idee8/shipfree/tree/main/docker/prod/Dockerfile"
    click ProdCompose "https://github.com/idee8/shipfree/blob/main/docker/prod/docker-compose.postgres.yml"
    click ProdCompose "https://github.com/idee8/shipfree/blob/main/docker/prod/docker-compose.mongodb.yml"
    click Database "https://github.com/idee8/shipfree/blob/main/src/db/schema.ts"
    click Database "https://github.com/idee8/shipfree/blob/main/src/db/index.ts"
    click DrizzleConfig "https://github.com/idee8/shipfree/blob/main/drizzle.config.ts"
    click GlobalsCSS "https://github.com/idee8/shipfree/blob/main/src/app/globals.css"

    %% Styles
    classDef frontend fill:#E8F0FE,stroke:#1A73E8,color:#1A73E8;
    classDef backend fill:#FEF3C7,stroke:#D97706,color:#B45309;
    classDef api fill:#ECFDF5,stroke:#10B981,color:#047857;
    classDef datastore fill:#FEF2F2,stroke:#DC2626,color:#B91C1C;
    classDef external fill:#F0FDF4,stroke:#059669,color:#065F46;
    classDef docker fill:#EFF6FF,stroke:#3B82F6,color:#1E3A8A;
    classDef config fill:#F5F3FF,stroke:#7C3AED,color:#5B21B6;
```
