Colorchef
Decoupled 'Ghost' Architecture: Next.js ISR, FastAPI Clustering & Git-as-a-Database
01. Context & Overview
Colorchef is a modular, all-in-one color and UI utility platform designed for indie developers, designers, and solopreneurs. It streamlines visual decision-making around colors, box shadows, dark themes, and UI components while serving as an aesthetic Cinema Palette Discovery Engine.
The project spans a three-tier decoupled “Ghost” architecture:
colorchef-next(Frontend UI & Discovery Engine): Built with Next.js (App Router, Incremental Static Regeneration) and Tailwind CSS, featuring Firebase for authentication and saved palettes.colorchef-server(Local Extraction & Ingestion Engine): A dedicated Python FastAPI backend with asynchronous HTTPX, custom color clustering algorithms, and TMDB API synchronization. Intended strictly for local private execution so that no write-capable endpoints are exposed to the public internet.colorchef-data(Single Source of Truth / Decoupled CMS): A Git repository serving as a version-controlled database and global CDN for static JSON assets, enabling hot-swappable business logic without frontend redeployments.
The platform provides six specialized design modules:
- 🎨 Colors: Generate and tweak harmonious color palettes (contrast-based or random) with one-click HEX clipboard copy.
- 🪞 Shadows: Visual box-shadow builder with real-time controls for offset, blur, spread, and opacity, exporting ready-to-paste CSS.
- 🌒 Dark Palette: Transform light palettes into accessible, contrast-adjusted dark theme variants while maintaining visual harmony.
- 🔘 Buttons: Design customizable interactive buttons with instant previews for normal, hover, and disabled states.
- 📐 Golden Ratio: Generate balanced palettes mathematically using golden ratio proportions or custom user-uploaded images.
- 🎬 Cinema: Discover aesthetic color palettes extracted directly from curated movie posters and high-resolution backdrops.
02. The Constraints & Needs
Building a high-performance, content-rich design discovery platform for indie developers required solving three key engineering constraints:
- Zero-Cost, High-Security Infrastructure: Exposing public admin REST endpoints and maintaining managed relational or document databases incurs ongoing cloud hosting costs and opens web attack surfaces. Colorchef uses a “Ghost” architecture where admin ingestion runs entirely locally and commits to Git.
- Algorithmic Palette Extraction from Cinematic Backdrops: Converting raw film posters and movie backdrops into cohesive, high-aesthetic 5-color palettes requires custom clustering algorithms that extract dominant tones while discarding visual noise.
- Hot-Swappable Business Logic without Frontend Redeploys: Modifying discovery taxonomy, horizontal filter bars (e.g., promoting “Cyberpunk” or “Folk Horror”), or search synonyms needed to occur dynamically without triggering full Next.js rebuilds or redeployments.
03. System Architecture & Data Flow
Colorchef’s decoupled multi-layer architecture separates local administrative operations from public edge delivery:
Colorchef Decoupled 'Ghost' Architecture
Local Python server triggers POST /admin/cinema/sync, fetching movie metadata and high-resolution backdrops asynchronously via TMDB.
Applies image clustering algorithms across backdrop pixels to extract aesthetically balanced HEX color palettes.
Rebuilds lightweight index.json, movie records, and config.json, committing directly to the colorchef-data repository.
Next.js frontend fetches static JSON from GitHub/CDN via Incremental Static Regeneration (ISR) with zero database overhead.
Client browser renders responsive UI tools (Colors, Shadows, Dark Palette, Buttons, Golden Ratio) with Firebase user auth.
04. Protocol & Sequence Lifecycle
The lifecycle trace below outlines how new cinema palette data moves from local administrative sync through the Git repository into the live Next.js application:
Cinema Ingestion & ISR Static Delivery Trace
05. Benchmark & Evaluation Matrix
Comparing traditional cloud-hosted database systems with Colorchef’s Decoupled “Ghost” Architecture:
Architecture & Operational Decisions
Comparative evaluation across design constraints and implementations
| System Area | Conventional Stack | Colorchef Architecture | Operational Result |
|---|---|---|---|
| Database Hosting Cost | $25–$60 / month (Hosted SQL / MongoDB) | $0.00 / month (Git repository SSOT) | 100% Infrastructure cost elimination |
| Admin Ingestion Security | Public REST write endpoints exposed to internet | Local-only 'Ghost' FastAPI service | Zero external write attack surface |
| Discovery Logic Updates | Frontend redeployment for filter or tag changes | Hot-swappable config.json (niche_map & filters) | Instant zero-downtime reconfiguration |
| Palette Processing | Heavy client-side image processing on every load | Asynchronous backend clustering with Next.js ISR | Static edge delivery with fast page loads |
06. Key Engineering Learnings
- Git as a Database for Editorial Systems: For content with frequent reads and infrequent, controlled writes, using a version-controlled Git repository (
colorchef-data) as an SSOT provides an immutable audit log, automated CDN distribution, and zero operational hosting costs. - Private “Ghost” Backends Minimize Risk: Keeping write-heavy administrative ingestion processes (
colorchef-server) strictly on local development machines completely eliminates public API vulnerability surfaces and removes the need for complex web application firewall setups. - Hot-Swappable Configuration Drives Agility: Isolating business parameters—such as
curated_filtersand theniche_mapsynonym expansion layer—inconfig.jsonallows instant changes to category promotion and smart search without modifying React components or redeploying the Next.js frontend. - Modular Utility Architecture: Designing standalone, single-purpose UI tools (Colors, Shadows, Dark Palette, Buttons, Golden Ratio) keeps client bundles lean while enabling seamless cross-module workflows for developer workflows.