Skip to content

Releases: AegisX-dev/FORMA

v1.3.1 — The Architect

14 Dec 14:49
@AegisX-dev AegisX-dev
v1.3.1
6bcd39b

Choose a tag to compare

View all tags
v1.3.1 — The Architect Latest
Latest

Focus: Zero-Fund Architecture & Open Source Governance

🧬 Zero-Fund Caching Strategy (DNA Hashing)

  • Implemented Deterministic Input Hashing (SHA-256) to reduce AI API costs by ~90%.
  • Architecture: Requests are hashed -> Database is checked -> Cached plan returned instantly (300ms) or generated via Gemini if new.
  • Impact: Eliminates redundant API calls for popular workout configurations.

🛡️ Open Source Governance

  • Public Release: Repository migrated to Open Source.
  • Guardrails: Added LICENSE (MIT) and CONTRIBUTING.md.
  • CI/CD Pipeline: GitHub Actions now enforce strict linting and build checks on every Pull Request.
  • Issue Templates: Standardized bug reports and feature requests.

🐛 Bug Fixes & Improvements

  • Fixed const vs let assignment error in fallback logic.
  • Resolved strictly typed linting errors in API routes.
  • Stabilized Vercel build process with environment variable validation.
Assets 2
Loading

v1.3.0 — The Neural Admin Update

12 Dec 06:39
@AegisX-dev AegisX-dev
v1.3
d080010

Choose a tag to compare

View all tags
v1.3.0 — The Neural Admin Update

FORMA v1.3 — Release Summary

Release Date: December 12, 2025
Codename: The Brain
Focus: AI-Powered Admin Tools & Database Automation

🎯 Overview

Version 1.3 introduces the Neural Ingestor — an AI-powered admin pipeline that transforms raw PDF documents into structured exercise database entries. This internal tool dramatically accelerates content expansion and eliminates manual data entry.

Live Demo: forma-two.vercel.app
Admin Access: /admin (PIN-protected)

✨ New Features

Feature Description Status
🧬 Neural Ingestor AI-powered PDF → Database pipeline using Gemini 2.5 Flash Lite ✅ SHIPPED
🔐 Admin Dashboard PIN-protected /admin route for database management ✅ SHIPPED
🧠 Smart Deduplication Prevents duplicate exercises with case-insensitive name matching ✅ SHIPPED
⚡ Batch Processing Handles 100k+ characters, inserts exercises in <10 seconds ✅ SHIPPED
📄 Multi-Format Support Accepts PDF, CSV, and TXT file uploads ✅ SHIPPED

🔧 Technical Implementation

1. Neural Ingestor Pipeline

The Neural Ingestor transforms unstructured documents into structured database records:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Upload    │ → │   Parse     │ → │   Extract   │ → │   Dedupe    │ → │   Insert    │
│  PDF/TXT    │    │  pdf2json   │    │   Gemini    │    │  Name Check │    │  Supabase   │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘

API Route: app/api/admin/ingest/route.ts

// 1. PDF Parsing (Server-side, no DOM dependencies)
import PDFParser from "pdf2json";

function parsePdf(buffer: Buffer): Promise<string> {
  return new Promise((resolve, reject) => {
    const parser = new PDFParser(null, 1);
    parser.on("pdfParser_dataReady", () => resolve(parser.getRawTextContent()));
    parser.on("pdfParser_dataError", (err) => reject(err.parserError));
    parser.parseBuffer(buffer);
  });
}

// 2. AI Extraction (Structured JSON output)
const result = await model.generateContent({
  contents: [{ role: "user", parts: [{ text: systemPrompt }] }],
  generationConfig: {
    responseMimeType: "application/json", // Guaranteed valid JSON
  },
});

// 3. Smart Deduplication
const { data: existingData } = await supabase.from("exercises").select("name");
const existingNames = new Set(existingData?.map((e) => e.name.toLowerCase()));
const uniqueExercises = exercises.filter(
  (ex) => !existingNames.has(ex.name.toLowerCase())
);

Impact: 20+ exercises can be added from a single PDF upload in seconds.

2. Admin Dashboard UI

New app/admin/page.tsx with Refined Brutalism styling:

PIN Authentication:

const handlePinSubmit = (e: React.FormEvent) => {
  e.preventDefault();
  const correctPin = process.env.NEXT_PUBLIC_ADMIN_PIN;

  if (pinInput === correctPin) {
    setIsAuthenticated(true);
    sessionStorage.setItem("forma_admin_auth", "true");
  }
};

Manual Entry Form:

  • Exercise Name (text input)
  • Target Muscle (dropdown: Chest, Back, Legs, Shoulders, Arms, Abs)
  • Equipment (multi-select toggle buttons)
  • Difficulty Tier (Beginner / Intermediate / Advanced)
  • Science Note (textarea)

Neural Ingest Zone:

  • Drag-and-drop file upload
  • Animated loading state: "AI is analyzing document..."
  • Result panel showing extracted exercise names

Impact: Fast, keyboard-friendly interface for rapid database expansion.

3. Service Role Authentication

The ingest API uses a separate Supabase client with Service Role privileges:

// ❌ BAD: Anon key (restricted by RLS)
import { supabase } from "@/lib/supabase";

// ✅ GOOD: Service Role key (bypasses RLS for admin writes)
const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
);

Impact: Admin can insert exercises without modifying RLS policies.

4. AI Extraction Prompt

The Gemini prompt ensures consistent, database-ready output:

const systemPrompt = `You are a data extraction engine. Analyze the following text and extract all fitness exercises mentioned.

Return a JSON Array where each object has:
{
  "name": "Exercise Name",
  "target_muscle": "Primary muscle group",
  "equipment": ["Equipment1", "Equipment2"],
  "difficulty": "Beginner/Intermediate/Advanced",
  "instructions": "Brief description or cues"
}

STRICT RULES:
- target_muscle MUST be one of: Chest, Back, Legs, Shoulders, Arms, Abs
- equipment should be an array like: ["Barbell"], ["Dumbbell", "Bench"], ["Bodyweight"]
- If difficulty is unclear, default to "Intermediate"
- Extract ALL exercises found, even if partially described
- Do NOT invent exercises not mentioned in the text`;

Impact: Structured extraction with validation rules baked into the prompt.

📁 Files Added

src/
├── app/
│   ├── admin/
│   │   └── page.tsx              # PIN-protected admin dashboard
│   └── api/
│       └── admin/
│           └── ingest/
│               └── route.ts      # Neural Ingestor API endpoint
└── types/
    └── pdf2json.d.ts             # TypeScript declarations for pdf2json

🔑 Environment Variables

# Existing
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
GEMINI_API_KEY_1=your_gemini_key

# New in v1.3
NEXT_PUBLIC_ADMIN_PIN=your_secret_pin
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

📊 Performance Metrics

Metric Value
PDF Parse Time ~500ms (10-page PDF)
AI Extraction Time ~3-5 seconds
Database Insert Time ~200ms (batch)
Total Pipeline Time <10 seconds
Max Document Size 100k+ characters
Exercises per Upload 20-50 typical

🛡️ Safety Features

  1. PIN Protection — Admin UI requires correct PIN from environment variable
  2. Session Persistence — Auth stored in sessionStorage (survives refresh)
  3. Smart Deduplication — Case-insensitive name matching prevents duplicates
  4. Service Role Isolation — Admin writes use separate Supabase client
  5. Graceful Errors — User-friendly messages for all failure modes

🚀 Upgrade Path

From v1.2.1 to v1.3:

  1. Add new environment variables to .env.local:

    NEXT_PUBLIC_ADMIN_PIN=your_secret_pin
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

  2. Install new dependency:

    npm install pdf2json

  3. Access admin dashboard at /admin

📜 License

Copyright © 2025 Forma. All rights reserved.

FORMA v1.3 — The Brain
AI-powered database automation for the modern fitness platform.

Loading

v1.2.1 — The Stability & Intel Update

09 Dec 17:48
@AegisX-dev AegisX-dev
v1.2.1
1579764

Choose a tag to compare

View all tags
v1.2.1 — The Stability & Intel Update

v1.2.1 — The Stability & Intel Update

Focus: Bulletproof Reliability & "Waiting Room" UX
Status: 🟢 Production Ready

This patch eliminates the "White Screen of Death" caused by API rate limits and turns the waiting time into a valuable learning experience.

✨ New Features

  • 🧠 Intel Loader: Replaced the generic loading spinner with a Goal-Based Science Feed.
    • Users now receive "Science Tips" specific to their goal (e.g., Hypertrophy: "Control the eccentric phase...") while the AI builds their plan.
    • Features a new CSS-based "Pulsating Core" animation.
  • 🛡️ API Key Rotation Engine: Implemented a backend failover system that rotates through 3 distinct API keys (Primary, Backup 1, Backup 2) to automatically bypass Google Gemini's 429 Rate Limit errors.

🔧 Technical Improvements

  • Payload Minification: Refactored the AI context injection to strip 60% of data (sending only ID/Name/Muscle) before prompting. This reduced gemini-2.5-flash latency significantly.
  • Crash Guards: Added comprehensive try/catch blocks to page.tsx and route.ts. 500 Errors now trigger a "System Busy" UI instead of crashing the app.
  • Privacy Fix: Disabled Supabase session persistence to resolve Access to storage is not allowed errors in Incognito/Brave browsers.

📦 Deploy

Live build: forma-two.vercel.app

Loading

v1.2 — The Professional

06 Dec 07:56
@AegisX-dev AegisX-dev
v1.2
eb1afd5

Choose a tag to compare

View all tags
v1.2 — The Professional

FORMA v1.2 — Release Summary

Release Date: December 6, 2025
Codename: The Professional
Focus: UX Polish & Premium Feel

🎯 Overview

Version 1.2 is a UX-focused release that transforms FORMA from a functional tool into a premium, polished product. This update introduces interactive visual elements, adaptive input components, and multi-goal training support.

Live Demo: forma-two.vercel.app

✨ New Features

Feature Description Status
🎡 Adaptive Duration Picker iOS-style drum wheel on mobile, horizontal slider on desktop ✅ SHIPPED
🎯 Multi-Goal Selection Select multiple goals (e.g., Hypertrophy + Strength) for hybrid training ✅ SHIPPED
🌌 Interactive Grid Background Cursor-tracking spotlight effect with CSS masking ✅ SHIPPED
📱 Mobile Readability Responsive fonts, tap-to-toggle tooltips, improved card layout ✅ SHIPPED
📄 High-Contrast PDF Larger fonts, darker text, readable on mobile screens ✅ SHIPPED

🔧 Technical Changes

1. Adaptive Duration Picker Component

New DurationPicker.tsx component with device-specific UX:

Mobile (Ghostly Scroll Wheel):

// Fixed height constants for reliable scroll math
const ITEM_HEIGHT = 64;     // h-16 = 4rem = 64px
const CONTAINER_HEIGHT = 256; // h-64 = 16rem = 256px

// CSS masking for dissolving edges
maskImage: "linear-gradient(to bottom, transparent 0%, black 20%, black 80%, transparent 100%)"

// Active vs Inactive states (index-based tracking)
Active:   text-5xl font-black text-white scale-110
Inactive: text-3xl text-white/20 blur-[1px] scale-90

// Mount scroll position fix
const scrollTop = index * ITEM_HEIGHT;
container.scrollTo({ top: scrollTop, behavior: "auto" });

Desktop (Horizontal Slider):

// Acid green fill track
background: linear-gradient(to right, #D4FF00 0%, #D4FF00 ${fill}%, rgba(255,255,255,0.1) ${fill}%, ...)

Impact: Premium, tactile feel on both mobile and desktop.

2. Multi-Goal (Hybrid) Training

Frontend State Change:

// Before (single goal)
const [goal, setGoal] = useState<string>("HYPERTROPHY");

// After (multi-goal array)
const [goals, setGoals] = useState<string[]>(["HYPERTROPHY"]);

Backend Prompt Logic:

// Single goal
"Goal: Hypertrophy";

// Multiple goals
"Goal: Hybrid Training (Hypertrophy + Strength)";
"Focus: Blend volume for size with heavy compound lifts for strength.";

Impact: Users can now train for multiple adaptations simultaneously.

3. Interactive Grid Background

New InteractiveGrid.tsx component:

// Track cursor position via CSS variables (no re-renders)
container.style.setProperty("--x", `${e.clientX}px`);
container.style.setProperty("--y", `${e.clientY}px`);

// Spotlight reveal via CSS mask
maskImage: `radial-gradient(circle 200px at var(--x) var(--y), black 0%, transparent 100%)`;

Impact: Futuristic "scanning the void" effect — grid lines glow near cursor.

4. WorkoutCard Refactor

Tooltip Improvements:

  • Solid bg-paper (#111111) background — no text bleed-through
  • onClick toggle for mobile (replaces buggy :hover)
  • Icon swaps to X when tooltip is open

Responsive Typography:

  • Exercise name: text-lg md:text-xl
  • Specs: text-sm md:text-xs labels, text-base md:text-sm values

Impact: Cards are readable on all devices, tooltips work reliably on touch.

5. PDF High-Contrast Mode

// Header: fontSize 18 (was 16), black text
// Day headers: fontSize 14 (was 11), bold
// Column headers: Light grey background, black text
// Exercise names: fontSize 12 (was 9), black text
// Science notes: fontSize 9 (was 7), dark grey

Impact: PDF is now readable while training on a phone screen.

📁 Files Changed

src/
├── app/
│   ├── layout.tsx              # InteractiveGrid integration
│   ├── page.tsx                # Multi-goal state, DurationPicker, PDF styles
│   └── globals.css             # Slider styles, scrollbar-hide utility
├── components/
│   ├── DurationPicker.tsx      # NEW — Adaptive duration selector
│   ├── InteractiveGrid.tsx     # NEW — Cursor-tracking background
│   └── WorkoutCard.tsx         # Tooltip fix, responsive fonts
└── lib/
    └── gemini.ts               # Hybrid goal prompt logic

📊 UX Metrics

Metric v1.1 v1.2 Improvement
Mobile Readability Poor (small fonts) Excellent ✅ Fixed
Tooltip Usability Buggy on touch Tap-to-toggle ✅ Fixed
Goal Flexibility Single goal only Multi-goal hybrid ✅ New
Background Static grid Interactive spotlight ✅ Premium
PDF Legibility Low contrast High contrast ✅ Fixed

🚀 Deployment

git add .
git commit -m "Release v1.2: Duration picker, Multi-goal, Interactive grid, Mobile UX"
git push origin main

Deployed via Vercel auto-deploy on push to main.

🔮 What's Next (v1.3)

  • Exercise demo videos
  • Admin dashboard for exercise management
  • Additional equipment categories

📜 License

Copyright © 2025 Forma. All rights reserved.

FORMA v1.2 — The Professional
Premium. Polished. Production-Ready.

Loading

v1.1 — The Patch (Performance & Stability)

03 Dec 11:38
@AegisX-dev AegisX-dev
v1.1
afb96db

Choose a tag to compare

View all tags
v1.1 — The Patch (Performance & Stability)

FORMA v1.1 — Release Summary

Release Date: December 3, 2025
Codename: The Patch

🎯 Overview

Version 1.1 is a critical patch release focused on performance, logic fixes, and UX improvements based on real user feedback. This release reduces API latency by ~80% and fixes multiple breaking bugs.

Live Demo: forma-two.vercel.app

✅ Issues Fixed

Source Category Issue Solution Status
User #10 ⚡ Performance Random Errors / Timeout (49s → crash) Switched to gemini-2.0-flash + SQL payload optimization ✅ FIXED
User #7 🧠 Logic "Always 4 Days" Bug Strict day count enforcement in System Prompt ✅ FIXED
Tariq 🐞 Bug Unresponsive Scrolling Ghost form removal via display: none after animation ✅ FIXED
Vadim ⚙️ Architecture SQL Optimization .overlaps() filter + case normalization (DUMBBELL → Dumbbell) ✅ DONE
Noor ⚡ Performance "Loading feels slow" Latency reduced from 40s+ to ~8s ✅ MITIGATED

🔧 Technical Changes

1. Supabase Query Optimization

Before:

// Fetched ALL exercises (32 rows)
const { data } = await supabase.from("exercises").select("*");

After:

// Filter by user's equipment + case normalization
const formattedEquipment = userEquipment.map(
  (item) => item.charAt(0).toUpperCase() + item.slice(1).toLowerCase()
);

const { data } = await supabase
  .from("exercises")
  .select("readable_id, name, target_muscle, equipment, science_note")
  .overlaps("equipment", formattedEquipment);

Impact: Reduced token payload by 50-70%, faster Gemini response.

2. Strict Prompt Constraints

Added STRICT RULES section to AI prompt:

═══════════════════════════════════════════════════════════
STRICT RULES (MUST FOLLOW — NO EXCEPTIONS):
═══════════════════════════════════════════════════════════
1. DAYS CONSTRAINT: Generate EXACTLY X days. Not X+1, not X-1.
2. EXERCISE IDS: ONLY use IDs from DATA SOURCE.
3. VOLUME: Each day MUST contain 4-6 exercises.

Impact: Eliminated "always 4 days" bug, ensured proper volume per session.

3. DOM Cleanup Fix

Before:

// Form remained in DOM (invisible but blocking clicks)
animate(formRef.current, { opacity: 0 });

After:

// Form completely removed after animation
animate(formElement, {
  opacity: 0,
  onComplete: () => {
    formElement.style.display = "none";
  },
});

Impact: Fixed unresponsive scrolling, results now fully interactive.

4. Days Per Week Selector

Added new UI component:

  • State: daysPerWeek (default: 3)
  • Options: [3, 4, 5, 6] days
  • Styling: Inline styles for reliable background color

Impact: Users can now select training frequency (was hardcoded to 4).

📊 Performance Metrics

Metric v1.0 v1.1 Improvement
API Response Time 40-49s (timeout) ~8s 80% faster
Token Usage ~2000 tokens ~800 tokens 60% reduction
Error Rate High (timeout crashes) Low Stable

📁 Files Changed

src/
├── app/
│   ├── api/generate-plan/route.ts  # SQL filter + case normalization
│   └── page.tsx                     # Days selector + DOM cleanup
└── lib/
    └── gemini.ts                    # Strict prompt rules + volume constraint

🚀 Deployment

git add .
git commit -m "Release v1.1: Perf fix (Gemini 2.0), Logic fix (SQL Filter), UX fix (Scroll bug)"
git push origin main

Deployed via Vercel auto-deploy on push to main.

🔮 What's Next (v1.2)

  • Duration slider component
  • Multi-goal selection (Hypertrophy + Strength)
  • Visual polish (softer contrast)
  • Mobile responsiveness improvements

📜 License

Copyright © 2025 Forma. All rights reserved.

FORMA v1.1 — The Patch
Faster. Smarter. More Reliable.

Loading

v1.0.0 — Genesis

02 Dec 07:42
@AegisX-dev AegisX-dev
v1.0.0
b17334c

Choose a tag to compare

View all tags
v1.0.0 — Genesis

FORMA v1.0 — Release Summary

Release Date: December 2, 2025
Codename: Genesis

🎯 Overview

Version 1.0 marks the initial public release of FORMA — an AI-powered workout architecture system that generates science-backed fitness programs in seconds.

Live Demo: forma-two.vercel.app

✨ Core Features

Feature Description
Goal-Based Programming Three training modes: Hypertrophy, Strength, Endurance
AI Exercise Selection Gemini Flash AI selects optimal exercises based on user constraints
Science Notes Each exercise includes research-backed explanations on hover
Equipment Filtering Support for Barbell, Dumbbell, Cables, and Bodyweight
Session Duration Customizable workout length (in minutes)
PDF Export Download workout blueprints for offline use
Dynamic Loading Tactical loading sequence masks API latency

🏗 Architecture

Tech Stack

  • Framework: Next.js 14+ (App Router)
  • Language: TypeScript
  • Styling: Tailwind CSS
  • Database: Supabase (PostgreSQL)
  • AI Engine: Google Gemini Flash
  • Animations: Anime.js v4
  • PDF Generation: jsPDF
  • Deployment: Vercel

Design System — "Void Brutalism"

Token Value Usage
void #050505 Background
paper #111111 Card surfaces
acid #D4FF00 Primary accent
concrete #888888 Muted text

Typography:

  • Display: Syne (bold, uppercase)
  • Mono: JetBrains Mono

🧠 Key Technical Decisions

1. Logic-Only AI Pattern

The AI returns exercise IDs only (integers), not content. All exercise names, instructions, and science notes are fetched from Supabase. This eliminates hallucinations and reduces token usage by ~90%.

2. Readable ID System

Uses integer readable_id instead of UUIDs for AI context. Reduces token consumption and improves Gemini response latency.

3. Hybrid RAG Pipeline

Research papers → NotebookLM extraction → Human review → Supabase storage. The AI never generates exercise content — it only orchestrates selection logic.

📊 Database

Total Exercises: 32 (Base 12 + Expansion Pack 20)

Coverage by Muscle Group

Muscle Group Exercise Count
Chest 3
Back 5
Legs (Quads/Glutes/Hams) 8
Shoulders 6
Arms (Biceps/Triceps) 8
Calves 2

Schema Highlights

  • exercises table with RLS policies for public read access
  • generated_plans table for caching AI responses
  • GIN indexes on equipment arrays for fast filtering
  • Full seed data in src/sql/schema.sql

📁 File Structure

src/
├── app/
│   ├── api/generate-plan/route.ts   # POST endpoint for AI generation
│   ├── page.tsx                      # Main UI with form + results
│   ├── layout.tsx                    # Root layout with noise overlay
│   └── globals.css                   # Tailwind base styles
├── components/
│   └── WorkoutCard.tsx               # Exercise card with tooltip
├── lib/
│   ├── supabase.ts                   # Supabase client
│   └── gemini.ts                     # Gemini client + prompt builder
└── sql/
    └── schema.sql                    # Database schema + seed data

⚠️ Known Limitations

Limitation Status
Cold start latency (2-3s) on Vercel Free Tier Mitigated with loading sequence
Static exercise database Manual curation only
No user authentication Guest-only access
No workout history Single session only

🛣 Roadmap for v2.0

  • User authentication (Supabase Auth)
  • Workout history and progress tracking
  • Admin dashboard for exercise management
  • Weekly program generation (not just single sessions)
  • Exercise video integration
  • Mobile-responsive improvements

📜 License

Copyright © 2025 Forma. All rights reserved.

FORMA v1.0
Sculpted by Science. Architected by AI.

Loading