# davidmoralesz/instaplanner architecture

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

- Interactive diagram: https://gitdiagram.com/davidmoralesz/instaplanner
- Repository: https://github.com/davidmoralesz/instaplanner

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered React application built with Next.js 14.
- It provides a rich drag-and-drop interface for planning Instagram posts, uses an IndexedDB-backed local store for persistence, and bundles lightweight serverless API endpoints for documentation and maintenance mode.

##### File structure
- Top-level “app” directory: Next.js App Router files (layout.tsx, page.tsx, privacy, terms, releases, plus serverless API routes under app/api).
- “components” directory: reusable UI components, grouped by feature (dialogs, dnd, grid, ui primitives).
- “hooks”: custom React hooks for drag-and-drop, image management, keyboard nav, maintenance mode, etc.
- “lib”: utility code (dnd animations, storage adapters, image utilities, error definitions).
- “public/docs”: markdown files for privacy, terms, releases served via API and static routing.
- “config” and root config files: constants, environment typings, Next.js, Tailwind, Prettier, ESLint, Husky, GitHub Actions, Wrangler config for CF Workers deployment.

##### README for additional insights
- Stack: Next.js (server components + client components), TypeScript, Tailwind CSS, shadcn/ui, Framer Motion, dnd-kit.
- Storage: IndexedDB via a local abstraction in lib/storage.ts.
- Testing: Vitest + React Testing Library.
- Deployment via Cloudflare Workers using Wrangler.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        BrowserUI["Browser UI<br/>(Next.js Client Components)"]:::client
        subgraph "UI Components"
            direction TB
            AlertDialog["AlertDialog"]:::client
            Button["Button"]:::client
            Card["Card"]:::client
            Breadcrumb["Breadcrumb"]:::client
            Footer["Footer"]:::client
            Sidebar["Sidebar"]:::client
            ErrorBoundary["ErrorBoundary"]:::client
        end
        subgraph "Drag-and-Drop Module"
            direction TB
            DnDProvider["DnDProvider"]:::client
            DragOverlay["DragOverlay"]:::client
            useDnDHook["use-drag-and-drop Hook"]:::client
        end
        subgraph "Image Management"
            direction TB
            ImageUploader["ImageUploader"]:::client
            useImageHook["use-image-management Hook"]:::client
        end
        subgraph "Grid Display"
            direction TB
            ImageGrid["ImageGrid"]:::client
            ImageCard["ImageCard"]:::client
            SkeletonGrid["SkeletonGrid"]:::client
        end
        subgraph "Dialogs & Overlays"
            direction TB
            PreviewDialog["PreviewDialog"]:::client
            LightboxDialog["LightboxDialog"]:::client
            MaintenanceDialog["MaintenanceDialog"]:::client
            InstructionsDialog["InstructionsDialog"]:::client
            ClearDialog["ClearDialog"]:::client
        end
        subgraph "Custom Hooks"
            direction TB
            KeyboardNav["use-keyboard-navigation"]:::client
            HistoryHook["use-history"]:::client
            LightboxHook["use-lightbox-handlers"]:::client
            MobileDetect["use-mobile-detection"]:::client
            PageHandlers["use-page-handlers"]:::client
        end
        BrowserUI -->|uses| AlertDialog
        BrowserUI -->|uses| Button
        BrowserUI -->|uses| Card
        BrowserUI -->|uses| Breadcrumb
        BrowserUI -->|uses| Footer
        BrowserUI -->|uses| Sidebar
        BrowserUI -->|uses| ErrorBoundary
        BrowserUI -->|uses| DnDProvider
        BrowserUI -->|uses| DragOverlay
        BrowserUI -->|uses| useDnDHook
        BrowserUI -->|uses| ImageUploader
        BrowserUI -->|uses| useImageHook
        BrowserUI -->|uses| ImageGrid
        BrowserUI -->|uses| ImageCard
        BrowserUI -->|uses| SkeletonGrid
        BrowserUI -->|uses| PreviewDialog
        BrowserUI -->|uses| LightboxDialog
        BrowserUI -->|uses| MaintenanceDialog
        BrowserUI -->|uses| InstructionsDialog
        BrowserUI -->|uses| ClearDialog
        BrowserUI -->|uses| KeyboardNav
        BrowserUI -->|uses| HistoryHook
        BrowserUI -->|uses| LightboxHook
        BrowserUI -->|uses| MobileDetect
        BrowserUI -->|uses| PageHandlers
    end

    %% Server Layer
    subgraph "Server Layer (Edge Runtime)"
        direction TB
        NextServer["Next.js Server Components<br/>& API Routes"]:::server
        MaintenanceAPI["/api/maintenance"]:::server
        DocsAPI["/api/docs/[doc]"]:::server
        StaticPages["Privacy, Terms, Releases Pages"]:::server
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        IndexedDB["IndexedDB"]:::storage
        StorageAdapter["storage.ts Adapter"]:::storage
        StaticDocs["Static Docs Folder"]:::storage
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipeline"
        direction TB
        GHActions["GitHub Actions"]:::ci
        WranglerDeploy["Wrangler Deploy"]:::ci
        Cloudflare["Cloudflare Workers"]:::ci
    end

    %% Connections
    BrowserUI -->|SSR + CSS| NextServer
    NextServer -->|serves| BrowserUI
    BrowserUI -->|fetch docs| DocsAPI
    BrowserUI -->|check maintenance| MaintenanceAPI
    BrowserUI -->|read/write| IndexedDB
    StorageAdapter -->|abstraction| IndexedDB
    IndexedDB -->|via lib/storage.ts| StorageAdapter
    DocsAPI -->|reads| StaticDocs
    StaticPages -->|SSR| NextServer
    GHActions -->|build & test| WranglerDeploy
    WranglerDeploy -->|deploy| Cloudflare
    Cloudflare -->|runs| NextServer

    %% Click Events
    click BrowserUI "https://github.com/davidmoralesz/instaplanner/blob/main/app/layout.tsx"
    click BrowserUI "https://github.com/davidmoralesz/instaplanner/blob/main/app/page.tsx"
    click BrowserUI "https://github.com/davidmoralesz/instaplanner/blob/main/app/globals.css"
    click StaticPages "https://github.com/davidmoralesz/instaplanner/blob/main/app/privacy/page.tsx"
    click StaticPages "https://github.com/davidmoralesz/instaplanner/blob/main/app/terms/page.tsx"
    click StaticPages "https://github.com/davidmoralesz/instaplanner/blob/main/app/releases/page.tsx"
    click AlertDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/ui/alert-dialog.tsx"
    click Button "https://github.com/davidmoralesz/instaplanner/blob/main/components/ui/button.tsx"
    click Card "https://github.com/davidmoralesz/instaplanner/blob/main/components/ui/card.tsx"
    click Breadcrumb "https://github.com/davidmoralesz/instaplanner/blob/main/components/breadcrumb.tsx"
    click Footer "https://github.com/davidmoralesz/instaplanner/blob/main/components/footer.tsx"
    click Sidebar "https://github.com/davidmoralesz/instaplanner/blob/main/components/sidebar.tsx"
    click ErrorBoundary "https://github.com/davidmoralesz/instaplanner/blob/main/components/error-boundary.tsx"
    click DnDProvider "https://github.com/davidmoralesz/instaplanner/blob/main/components/dnd/dnd-provider.tsx"
    click DragOverlay "https://github.com/davidmoralesz/instaplanner/blob/main/components/dnd/drag-overlay.tsx"
    click useDnDHook "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-drag-and-drop.ts"
    click Animation "https://github.com/davidmoralesz/instaplanner/blob/main/lib/dnd/animation.ts"
    click Types "https://github.com/davidmoralesz/instaplanner/blob/main/lib/dnd/types.ts"
    click ImageUploader "https://github.com/davidmoralesz/instaplanner/blob/main/components/image-uploader.tsx"
    click useImageHook "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-image-management.ts"
    click imageUtils "https://github.com/davidmoralesz/instaplanner/blob/main/lib/image-utils.ts"
    click ImageGrid "https://github.com/davidmoralesz/instaplanner/blob/main/components/grid/image-grid.tsx"
    click ImageCard "https://github.com/davidmoralesz/instaplanner/blob/main/components/grid/image-card.tsx"
    click SkeletonGrid "https://github.com/davidmoralesz/instaplanner/blob/main/components/grid/skeleton-grid.tsx"
    click PreviewDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/dialogs/preview-dialog.tsx"
    click LightboxDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/dialogs/lightbox-dialog.tsx"
    click MaintenanceDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/dialogs/maintenance-dialog.tsx"
    click InstructionsDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/dialogs/instructions-dialog.tsx"
    click ClearDialog "https://github.com/davidmoralesz/instaplanner/blob/main/components/dialogs/clear-dialog.tsx"
    click MaintenanceAPI "https://github.com/davidmoralesz/instaplanner/blob/main/app/api/maintenance/route.ts"
    click DocsAPI "https://github.com/davidmoralesz/instaplanner/blob/main/app/api/docs/[doc]/route.ts"
    click useMarkdown "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-markdown-content.ts"
    click Documentation "https://github.com/davidmoralesz/instaplanner/blob/main/components/docs/documentation.tsx"
    click StaticDocs "https://github.com/davidmoralesz/instaplanner/tree/main/public/docs"
    click StorageAdapter "https://github.com/davidmoralesz/instaplanner/blob/main/lib/storage.ts"
    click Errors "https://github.com/davidmoralesz/instaplanner/blob/main/lib/errors.ts"
    click Utils "https://github.com/davidmoralesz/instaplanner/blob/main/lib/utils.ts"
    click KeyboardNav "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-keyboard-navigation.ts"
    click HistoryHook "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-history.ts"
    click LightboxHook "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-lightbox-handlers.ts"
    click MobileDetect "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-mobile-detection.ts"
    click PageHandlers "https://github.com/davidmoralesz/instaplanner/blob/main/hooks/use-page-handlers.ts"
    click GHActions "https://github.com/davidmoralesz/instaplanner/blob/main/.github/workflows/wrangler_deploy.yml"
    click GHActions "https://github.com/davidmoralesz/instaplanner/blob/main/.github/workflows/invalidate-docs.yml"
    click WranglerDeploy "https://github.com/davidmoralesz/instaplanner/blob/main/wrangler.jsonc"
    click nextConfig "https://github.com/davidmoralesz/instaplanner/blob/main/next.config.ts"
    click tailwindConfig "https://github.com/davidmoralesz/instaplanner/blob/main/tailwind.config.ts"
    click postcssConfig "https://github.com/davidmoralesz/instaplanner/blob/main/postcss.config.mjs"
    click prettierConfig "https://github.com/davidmoralesz/instaplanner/blob/main/prettier.config.cjs"
    click eslintConfig "https://github.com/davidmoralesz/instaplanner/blob/main/.eslintrc.json"
    click tsconfig "https://github.com/davidmoralesz/instaplanner/blob/main/tsconfig.json"
    click Constants "https://github.com/davidmoralesz/instaplanner/blob/main/config/constants.ts"
    click Env "https://github.com/davidmoralesz/instaplanner/blob/main/env.d.ts"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef server fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef storage fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef ci fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
