# valehernandezz/spookify architecture

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

- Interactive diagram: https://gitdiagram.com/valehernandezz/spookify
- Repository: https://github.com/valehernandezz/spookify

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js 13’s App Router, React, TypeScript and Tailwind CSS.
- It lets end users upload or pick images, apply AI-powered horror effects (via Perplexity API), manage image assets (via Cloudinary), then download or share the results.

##### Key file-structure insights
- Top level: next.config.mjs, tsconfig.json, Tailwind/PostCSS configs → a Next.js build and styling pipeline.
- src/app/ → Next.js App Router directory:
- (routes) contains dynamic pages (/[publicId], /editar).
- api/generate, api/upload, api/shared → serverless API routes.
- layout.tsx, globals.css, page.tsx etc. → root layout and entry points.
- src/hooks, src/lib, src/store → custom hooks, shared types/utilities, React context providers for state.

##### README-derived tech stack
- Next.js 13 (React) for UI and SSR/SSG.
- Cloudinary API for image storage, transformation, upload/presets.
- Perplexity API for generative-AI effects.
- Tailwind CSS for styling.
- TypeScript (static types) alongside some JSX.

##### Main components in the system design
a. Client (Browser)
- Next.js pages (SSR/SSG), React components, user interactions (upload, select tool, preview, download).
b. Next.js Frontend Layer
- app/layout.tsx as root, global CSS, navigation headers/footers.
- page components under src/app/(routes).
- React component tree under src/components.
- State management via Providers.tsx, custom hooks.
c. Next.js Backend Layer (Serverless Functions)
- /api/upload → receives raw image from client, calls Cloudinary upload API, returns asset URL.
- /api/generate → takes image URL + selected effect parameters, calls Perplexity API (or Cloudinary transformations), returns modified image URL.
- /api/shared → fetches public image by ID (from Cloudinary or metadata store).
d. External Services
- Cloudinary
- Storage of originals & derived images
- On-the-fly transformations (background replacement, overlays, cropping)
- Perplexity AI
- AI prompts to generate custom effects not covered by presets
e. Static Asset Store
- public/examples, public/tools, public/profiles for demo images and built-in assets.

##### Relationships and data flows
- User uploads image → Browser → POST /api/upload → Cloudinary → upload response → Browser updates state.
- User selects effect → Browser → POST /api/generate with image URL + effect ID → Perplexity API or Cloudinary transformation → returns new image URL → Browser updates preview.
- User downloads/shares → Browser either fetches from Cloudinary URL or routes through /api/shared → presents final asset.
- Next.js pages render via SSR/SSG, fetch initial data (e.g., examples) from public folder or service endpoints.

##### Architectural patterns & design principles
- Component-based UI (Atoms → Molecules → Organisms under src/components).
- Serverless functions as micro-APIs (each API route handles a single responsibility).
- Separation of concerns:
- UI (components, pages)
- State (context providers, hooks)
- Data access (API routes, lib/types)
- Externalize assets & transformations via third-party APIs instead of self-hosted services.
- Consistent styling via Tailwind utility classes.

##### Essential call-outs
- Root layout (src/app/layout.tsx) as the SSR entrypoint.
- State Provider component (src/store/Providers.tsx).
- API endpoints under src/app/api.
- Static asset folder feeding into SSR and client (public/*).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Browser
    browser["User Browser"]:::client

    %% Next.js Frontend (SSR & React)
    subgraph "Next.js Frontend (SSR & React)"
        layout["Root Layout"]:::client
        globals["Global Stylesheet"]:::client
        page["Home Page"]:::client
        share["Dynamic Share Page"]:::client
        edit["Image Edit Page"]:::client
        providers["State Providers"]:::client
        hooks["Custom Hooks"]:::client
        lib["Shared Utilities & Types"]:::client
        compDrop["Dropzone Component"]:::client
        toolsList["Tools List"]:::client
        genTool["Generate Transform"]:::client
        iconCloud["Cloudinary Icon"]:::client
        iconPerp["Perplexity Icon"]:::client
        header["Header Section"]:::client
        burger["Mobile Menu Toggle"]:::client
        hero["Hero Section"]:::client
        examples["Examples Gallery"]:::client
        toolsSec["Tools Section"]:::client
        aside["Aside Panel"]:::client
        footer["Footer Section"]:::client
        viewImg["View Image Component"]:::client
        imgCont["Image Container"]:::client
        editCtl["Image Edit Controls"]:::client
        cmpCtl["Image Compare Controls"]:::client
        btn["Button"]:::client
        loader["Loader"]:::client
        logo["Logo"]:::client
    end

    %% Static Assets
    subgraph "Static Assets (public)"
        examplesStatic["/examples"]:::static
        toolsStatic["/tools"]:::static
        profiles["/profiles"]:::static
    end

    %% Serverless API
    subgraph "Next.js Serverless API"
        apiUpload["POST /api/upload"]:::api
        apiGen["POST /api/generate"]:::api
        apiShared["GET /api/shared"]:::api
    end

    %% Config
    subgraph "Config"
        env["Env Vars (Cloudinary & Perplexity)"]:::config
        nextcfg["next.config.mjs"]:::config
        tailwindcfg["tailwind.config.ts"]:::config
        postcsscfg["postcss.config.mjs"]:::config
        tsconfig["tsconfig.json"]:::config
    end

    %% External Services
    subgraph "External Services"
        cloudAPI["Cloudinary REST API"]:::external
        perpAPI["Perplexity REST API"]:::external
    end

    %% Data Flows
    browser -->|"GET / (Initial SSR)"| layout
    layout -->|renders| page
    page -->|fetch assets| examplesStatic
    page -->|fetch assets| toolsStatic
    browser -->|"POST /api/upload"| apiUpload
    apiUpload -->|"upload image"| cloudAPI
    cloudAPI -->|"upload response \n(image URL)"| apiUpload
    apiUpload -->|"JSON response"| browser
    browser -->|"POST /api/generate"| apiGen
    apiGen -->|"AI effect request"| perpAPI
    perpAPI -->|"AI image URL"| apiGen
    apiGen -->|"transform request"| cloudAPI
    cloudAPI -->|"transformed URL"| apiGen
    apiGen -->|"JSON response"| browser
    browser -->|"GET /api/shared?publicId"| apiShared
    apiShared -->|"fetch image"| cloudAPI
    cloudAPI -->|"image data"| apiShared
    apiShared -->|"JSON response"| browser

    %% Click Events
    click layout "https://github.com/valehernandezz/spookify/blob/main/src/app/layout.tsx"
    click globals "https://github.com/valehernandezz/spookify/blob/main/src/app/globals.css"
    click page "https://github.com/valehernandezz/spookify/blob/main/src/app/page.tsx"
    click share "https://github.com/valehernandezz/spookify/blob/main/src/app/(routes)/[publicId]/page.tsx"
    click edit "https://github.com/valehernandezz/spookify/blob/main/src/app/(routes)/editar/page.tsx"
    click apiUpload "https://github.com/valehernandezz/spookify/blob/main/src/app/api/upload/route.ts"
    click apiGen "https://github.com/valehernandezz/spookify/blob/main/src/app/api/generate/route.ts"
    click apiShared "https://github.com/valehernandezz/spookify/blob/main/src/app/api/shared/route.ts"
    click providers "https://github.com/valehernandezz/spookify/blob/main/src/store/Providers.tsx"
    click hooks "https://github.com/valehernandezz/spookify/blob/main/src/hooks/useTransform.ts"
    click lib "https://github.com/valehernandezz/spookify/blob/main/src/lib/index.ts"
    click compDrop "https://github.com/valehernandezz/spookify/blob/main/src/components/dropzone/FormImage.jsx"
    click toolsList "https://github.com/valehernandezz/spookify/blob/main/src/components/tools/ListOfTools.jsx"
    click genTool "https://github.com/valehernandezz/spookify/blob/main/src/components/tools/GenerateTransform.jsx"
    click iconCloud "https://github.com/valehernandezz/spookify/blob/main/src/components/icons/tools/Cloudinary.jsx"
    click iconPerp "https://github.com/valehernandezz/spookify/blob/main/src/components/icons/tools/Perplexity.jsx"
    click header "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/header/Header.jsx"
    click burger "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/header/Hamburguer.jsx"
    click hero "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/Hero.jsx"
    click examples "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/Examples.jsx"
    click toolsSec "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/Tools.jsx"
    click aside "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/Aside.jsx"
    click footer "https://github.com/valehernandezz/spookify/blob/main/src/components/sections/Footer.jsx"
    click viewImg "https://github.com/valehernandezz/spookify/blob/main/src/components/image/ViewImage.jsx"
    click imgCont "https://github.com/valehernandezz/spookify/blob/main/src/components/image/ImageContainer.jsx"
    click editCtl "https://github.com/valehernandezz/spookify/blob/main/src/components/image/CtlImageEdit.jsx"
    click cmpCtl "https://github.com/valehernandezz/spookify/blob/main/src/components/image/CtlImageCompare.jsx"
    click btn "https://github.com/valehernandezz/spookify/blob/main/src/components/utils/Button.tsx"
    click loader "https://github.com/valehernandezz/spookify/blob/main/src/components/utils/Loader.jsx"
    click logo "https://github.com/valehernandezz/spookify/blob/main/src/components/utils/Logo.jsx"
    click examplesStatic "https://github.com/valehernandezz/spookify/tree/main/public/examples"
    click toolsStatic "https://github.com/valehernandezz/spookify/tree/main/public/tools"
    click profiles "https://github.com/valehernandezz/spookify/tree/main/public/profiles"
    click nextcfg "https://github.com/valehernandezz/spookify/blob/main/next.config.mjs"
    click tailwindcfg "https://github.com/valehernandezz/spookify/blob/main/tailwind.config.ts"
    click postcsscfg "https://github.com/valehernandezz/spookify/blob/main/postcss.config.mjs"
    click tsconfig "https://github.com/valehernandezz/spookify/blob/main/tsconfig.json"

    %% Styles
    classDef client fill:#AEDFF7,stroke:#000
    classDef api fill:#A8E6A1,stroke:#000
    classDef external fill:#F5B970,stroke:#000
    classDef static fill:#D3D3D3,stroke:#000
    classDef config fill:#FFC0CB,stroke:#000
```
