Skip to content

Unrestricted Open-source alternative to AI video platforms — Free AI image & video generation studio with 600+ models (Flux, Midjourney, Kling, Sora, Veo). No content filters. Self-hosted, MIT licensed.

docs: Add comprehensive project knowledge and vision document

Anil Matchac30891eeb6fb
diff --git a/project_knowledge.md b/project_knowledge.md
new file mode 100644
index 00000000..8dbce995
--- /dev/null
+++ b/project_knowledge.md
@@ -0,0 +1,99 @@
+# Open Higgsfield AI: Technical Documentation & Context
+
+This document serves as a comprehensive knowledge base for the Open Higgsfield AI project. It details the architecture, key components, API integration patterns, and state management strategies used in the application.
+
+## 1. Project Vision & Overview
+
+**Open Higgsfield AI** is an ambitious open-source project dedicated to **replicating the full functionality of the Higgsfield platform**.
+
+- **Core Goal:** To build a feature-complete, self-hosted alternative to Higgsfield, starting with **Image Generation** (Nano) and expanding into **Video Generation** (Cinema) and other creative tools.
+- **Current State:** The Image Studio ("Nano Banana Pro" interface) is fully operational, featuring a premium dark-mode UI, history management, and multi-model support via the [Muapi.ai](https://muapi.ai) engine.
+- **Future Direction:** The architecture is designed to scale for video generation, model training interfaces, and advanced editing tools, mirroring the evolving capabilities of Higgsfield.
+
+- **Stack:** Vite, Vanilla JavaScript, Tailwind CSS v4.
+- **Repository:** `https://github.com/Anil-matcha/Open-Higgsfield-AI`
+- **Primary Branch:** `main`
+
+## 2. Architecture & File Structure
+
+The project follows a component-based architecture using vanilla JS, where each component is a function that returns a DOM element.
+
+```tree
+src/
+├── components/
+│ ├── ImageStudio.js # Core logic: Prompts, model picking, canvas, history.
+│ ├── Header.js # Navigation, user settings, auth status.
+│ ├── AuthModal.js # Modal for capturing and validating the API key.
+│ ├── SettingsModal.js # Panel for managing settings (clearing API key).
+│ └── Sidebar.js # (Currently unused/placeholder) Navigation sidebar.
+├── lib/
+│ ├── muapi.js # The API Client. Handles auth, submission, and polling.
+│ └── models.js # Source of truth for model definitions and endpoints.
+├── styles/
+│ ├── global.css # Global resets, fonts, and animation keyframes.
+│ ├── studio.css # Specific styles for the studio interface.
+│ └── variables.css # CSS custom properties (colors, blur amounts).
+├── main.js # Entry point. Renders the app layout and Header/Studio.
+└── style.css # Tailwind CSS entry file (imports other CSS).
+```
+
+## 3. Key Components & Logic
+
+### `ImageStudio.js` (The Brain)
+This is the most complex component. It handles:
+- **State:** Selected model (`selectedModel`), aspect ratio (`selectedAr`), and generation status.
+- **Prompt Input:** A textarea with auto-grow logic and max-height constraints (fixed in `bf2efdb`).
+- **Dynamic Controls:**
+ - **Model Picker:** Lists models from `models.js`.
+ - **Quality/Resolution:** Only appears for models with explicit resolution support (like `nano-banana-pro`). Hidden for others (like `flux-schnell`).
+- **Generation Flow:**
+ 1. Checks for API key in `localStorage`. If missing, opens `AuthModal`.
+ 2. Calls `muapi.generateImage()`.
+ 3. Polling loop waits for result.
+ 4. On success, adds result to `generationHistory` and displays it.
+- **History:**
+ - Stored in `localStorage` key `muapi_history`.
+ - Slides in from the right sidebar.
+ - Thumbnails are clickable to re-view; hover to download.
+
+### `muapi.js` (The Engine)
+Encapsulates all communication with `api.muapi.ai`.
+- **Authentication:** Uses `x-api-key` header (NOT `Authorization: Bearer`).
+- **Pattern:** Submit -> Poll.
+ - `POST` to endpoint (e.g., `/api/v1/nano-banana-pro`).
+ - API returns a `request_id`.
+ - `POST` / `GET` loop on `/api/v1/predictions/{id}/result` until status is `completed`, `succeeded`, or `failed`.
+- **Normalization:** The polling response structure varies. `muapi.js` normalizes the result to ensure `url` is always populated (extracting from `outputs[0]` if necessary).
+
+### `models.js` (The Data)
+Contains the `t2iModels` array.
+- Each model has an `id`, `name`, `inputs` schema (resolution, aspect ratio support), and a crucial `endpoint` property.
+- **Crucial:** The `endpoint` property maps the internal ID to the API path (e.g., `flux-schnell` -> `flux-schnell-image`).
+
+## 4. UI & Styling (Tailwind v4)
+
+- **Theme:** Dark mode by default (`bg-app-bg` = `#050505`).
+- **Accent:** Neon Yellow-Green (`#d9ff00`) used for primary actions and glows.
+- **Glassmorphism:** Extensive use of `backdrop-blur` and `bg-white/5` or `bg-black/60` for panels, headers, and modals.
+- **Responsiveness:**
+ - **Mobile:** Stacked layout, simplified controls, hidden sidebar.
+ - **Desktop:** Wide canvas, floating prompt bar, side-by-side history.
+- **Animations:** Custom keyframes in `global.css` for `fade-in-up`, `pulse-glow`, etc.
+
+## 5. Development Setup
+
+- **Vite Proxy:** Local development uses a proxy in `vite.config.js` to route `/api` requests to `https://api.muapi.ai` to avoid CORS issues.
+- **Environment:** `muapi.js` detects `import.meta.env.DEV` to decide whether to use the relative `/api` path (proxy) or the full URL (production).
+
+## 6. Known Gotchas & Fixes
+
+- **Prompt Bar Overflow:** Fixed by limiting textarea max-height and enabling scrolling.
+- **Flux Resolution Picker:** Fixed logic to only show the resolution picker if the model *explicitly* lists enum values for resolution/megapixels.
+- **Hero Visibility:** The "Nano Banana Pro" hero text is completely hidden (`display: none`) when an image is shown to prevent bleed-through.
+- **API Key Logging:** Debug logs printing the API key were removed for security.
+
+## 7. Future Roadmap (Potential)
+
+- **Video Generation:** Expand `models.js` and `ImageStudio.js` to support video models (already present in `schema_data` but not wired up).
+- **In-painting/Out-painting:** Add canvas editing tools.
+- **User Accounts:** Move beyond local storage for history.