# mckaywrigley/mckays-app-template architecture

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

- Interactive diagram: https://gitdiagram.com/mckaywrigley/mckays-app-template
- Repository: https://github.com/mckaywrigley/mckays-app-template

## Overview

##### Main Components
- Frontend Application:
- All files inside the "app" directory contain page routes and layouts including dedicated sections for authentication ((auth)), marketing ((marketing)), and feature-specific parts like "todo".
- The "components" and "components/ui" directories hold reusable UI components (headers, sidebars, buttons, etc.) which are integrated into the pages.
- The "components/magicui" and "components/utilities" directories provide further reusable elements (such as animations, theming, and analytics integration).

- API & Server Actions:
- The "app/api" folder (with its stripe/webhooks endpoint) and the "actions" folder (which has action scripts for db and stripe operations) represent the backend API endpoints and server actions used to perform business logic.
- Server Actions are tightly coupled with the new Next.js app router capabilities.

- Backend / Database Layer:
- In the "db" directory, you have migration scripts and schema definitions that indicate interactions with a PostgreSQL database (via Supabase and Drizzle ORM).
- Environment variables in the README show that the DATABASE_URL is used to connect to a PostgreSQL database (hosted on Supabase).

- External Services & Integrations:
- Auth is managed through Clerk (as indicated by the necessary environment variables and the (auth) page routes).
- Payments are handled via Stripe (with dedicated action scripts and API webhook support).
- Analytics are integrated using PostHog (as seen in the "components/utilities/posthog" directory).

##### Relationships and Interactions
- The Client (Browser) interacts with the Frontend:
- The user accesses different routes (marketing, auth, todo) which are rendered by Next.js pages and layouts.
- UI components are composed together to form each page (headers, sidebars, etc.).

- The Frontend Layer interacts with Server Actions & API Endpoints:
- When users perform actions (logging in, signing up, interacting with todo items, or payment events), the frontend calls the appropriate backend endpoints.
- For example, server actions in the "actions/db" directory manage database CRUD operations and interact with the DB layer.

- Backend Connectivity and External Services:
- The server endpoints may invoke external APIs or services:
» Clerk for managing user authentication flows.
» Stripe APIs for handling payments and webhooks.
» PostHog for capturing analytics events.
- The DB layer (with its migrations and schemas) is used for persisting application data using Supabase/PostgreSQL.

##### Architectural Patterns and Design Principles
- Modular Separation:
- The separation between UI (pages, components), server actions (business logic), and persistence (database with migrations) illustrates a modular and layered architecture.
- Reusability and Componentization:
- With many directories dedicated to UI elements and utilities, there is a clear emphasis on reusable components (e.g., the "components" and "lib/hooks" folders).
- Integration with External Tools:
- The application leverages external services via clearly separated integration points (for auth, payments, and analytics), making it easy to update or replace them if necessary.

##### Incorporate the Relevant Technologies and Frameworks
- Frontend: Next.js (with the new App Router), Tailwind CSS, Shadcn UI, Framer Motion
- Backend/Database: PostgreSQL with Supabase, using Drizzle ORM for database interactions
- Authentication: Clerk
- Payments: Stripe
- Analytics: PostHog
- Developer Tools: Cursor IDE, ESLint, Husky for git hooks, Prettier for code formatting

##### Final Detailed Description for the Principal Software Engineer
- Frontend with API endpoints and server actions that process business logic.
- How these endpoints interact with a centralized database (including references to migrations and ORMs).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    Client_Browser["Client (Browser)"]:::frontend
    NextJS_Frontend["Next.js Frontend (app)"]:::frontend
    Client_Browser -->|"requests"| NextJS_Frontend
    click NextJS_Frontend "https://github.com/mckaywrigley/mckays-app-template/tree/main/app"

    subgraph "Frontend Routes"
        Auth_Routes["Authentication Pages"]:::frontend
        Marketing_Routes["Marketing Pages"]:::frontend
        Todo_Routes["Todo Feature Pages"]:::frontend
    end
    NextJS_Frontend -->|"renders"| Auth_Routes
    NextJS_Frontend -->|"renders"| Marketing_Routes
    NextJS_Frontend -->|"renders"| Todo_Routes
    click Auth_Routes "https://github.com/mckaywrigley/mckays-app-template/tree/main/app/(auth)"
    click Marketing_Routes "https://github.com/mckaywrigley/mckays-app-template/tree/main/app/(marketing)"
    click Todo_Routes "https://github.com/mckaywrigley/mckays-app-template/tree/main/app/todo"

    subgraph "UI Components"
        Components_Main["Components"]:::ui
        UI_Dir["UI Catalog"]:::ui
        Sidebar["Sidebar"]:::ui
        Landing["Landing"]:::ui
        MagicUI["MagicUI"]:::ui
    end
    NextJS_Frontend -->|"composes"| Components_Main
    Components_Main --> UI_Dir
    Components_Main --> Sidebar
    Components_Main --> Landing
    Components_Main --> MagicUI
    click Components_Main "https://github.com/mckaywrigley/mckays-app-template/tree/main/components"
    click UI_Dir "https://github.com/mckaywrigley/mckays-app-template/tree/main/components/ui"
    click Sidebar "https://github.com/mckaywrigley/mckays-app-template/tree/main/components/sidebar"
    click Landing "https://github.com/mckaywrigley/mckays-app-template/tree/main/components/landing"
    click MagicUI "https://github.com/mckaywrigley/mckays-app-template/tree/main/components/magicui"

    %% Application Layer - Server Actions & API Endpoints
    subgraph "Server Actions & API"
        Actions_DB["DB Actions (actions/db)"]:::api
        Stripe_Actions["Stripe Actions"]:::api
        API_Stripe_Webhooks["Stripe Webhooks API"]:::api
    end
    Todo_Routes -->|"triggers"| Actions_DB
    NextJS_Frontend -->|"invokes"| Stripe_Actions
    NextJS_Frontend -->|"receives"| API_Stripe_Webhooks
    click Actions_DB "https://github.com/mckaywrigley/mckays-app-template/tree/main/actions/db"
    click Stripe_Actions "https://github.com/mckaywrigley/mckays-app-template/blob/main/actions/stripe-actions.ts"
    click API_Stripe_Webhooks "https://github.com/mckaywrigley/mckays-app-template/blob/main/app/api/stripe/webhooks/route.ts"

    %% Data Layer - Database
    subgraph "Database (Supabase/PostgreSQL)"
        DB_Main["DB Connection (db/db.ts)"]:::backend
        DB_Migrations["Migrations"]:::backend
        DB_Schema["Schema"]:::backend
    end
    Actions_DB -->|"persists"| DB_Main
    Stripe_Actions -->|"updates"| DB_Main
    DB_Main -->|"uses"| DB_Migrations
    DB_Main -->|"defines"| DB_Schema
    click DB_Migrations "https://github.com/mckaywrigley/mckays-app-template/tree/main/db/migrations"
    click DB_Schema "https://github.com/mckaywrigley/mckays-app-template/tree/main/db/schema"
    click DB_Main "https://github.com/mckaywrigley/mckays-app-template/blob/main/db/db.ts"

    %% External Services
    subgraph "External Services"
        Clerk["Clerk (Auth)"]:::external
        Stripe_Ext["Stripe (Payments)"]:::external
        PostHog_Ext["PostHog (Analytics)"]:::external
    end
    Auth_Routes -->|"auth calls"| Clerk
    Stripe_Actions -->|"payment calls"| Stripe_Ext
    API_Stripe_Webhooks -->|"webhook events"| Stripe_Ext

    %% PostHog Integration within UI
    subgraph "PostHog Integration"
        PostHog_PageView["PostHog Pageview"]:::analytics
        PostHog_Provider["PostHog Provider"]:::analytics
        PostHog_UserIdentity["PostHog User Identity"]:::analytics
    end
    UI_Dir -->|"tracks"| PostHog_PageView
    Marketing_Routes -->|"analytics"| PostHog_PageView
    PostHog_PageView --> PostHog_Ext
    PostHog_Provider --> PostHog_Ext
    PostHog_UserIdentity --> PostHog_Ext
    click PostHog_PageView "https://github.com/mckaywrigley/mckays-app-template/blob/main/components/utilities/posthog/posthog-pageview.tsx"
    click PostHog_Provider "https://github.com/mckaywrigley/mckays-app-template/blob/main/components/utilities/posthog/posthog-provider.tsx"
    click PostHog_UserIdentity "https://github.com/mckaywrigley/mckays-app-template/blob/main/components/utilities/posthog/posthog-user-identity.tsx"

    %% Styling Classes
    classDef frontend fill:#DDEEFF,stroke:#1E90FF,stroke-width:2px;
    classDef ui fill:#FFEFD5,stroke:#DAA520,stroke-width:2px;
    classDef api fill:#FFFACD,stroke:#FF8C00,stroke-width:2px;
    classDef backend fill:#E0FFFF,stroke:#20B2AA,stroke-width:2px;
    classDef external fill:#FFE4E1,stroke:#FF4500,stroke-width:2px;
    classDef analytics fill:#F0E68C,stroke:#DAA520,stroke-width:2px;
```
