IntentForge

Stack: Next.js 16, React 19, TypeScript, Tailwind CSS, Zod, Vercel AI SDK, Google Gemini, Supabase Auth, Supabase PostgreSQL, IndexedDB, Upstash Redis, Vitest, Playwright

Tags: Full Stack, AI, Prompt Engineering, Next.js, Supabase, Local First, Portfolio App

IntentForge is a structured prompt-generation web app that turns rough natural-language requests into execution-ready AI instructions. The application helps users move from vague intent to a more complete prompt with objectives, requirements, constraints, deliverables, assumptions, missing-context placeholders, readiness feedback, and exportable Markdown/text output.

Problem

People often ask AI agents to do complex work with incomplete or loosely formed instructions. The result is usually a brittle prompt: missing constraints, unclear deliverables, unknown context, weak testing criteria, and ambiguous target-agent expectations. IntentForge exists to make that instruction-building step more deliberate.

Intended Users

• Developers, founders, students, researchers, writers, designers, analysts, marketers, educators, and operators who delegate complex work to AI systems.
• Portfolio visitors and technical recruiters who want to see a production-style AI app with authentication, database ownership boundaries, local-first storage, and cost controls.

What It Does

• Accepts a raw user request.
• Classifies the task into one of ten categories.
• Selects a task framework and target-agent shape.
• Detects missing context and inserts explicit placeholders.
• Generates a structured prompt object through a provider interface.
• Validates provider output with Zod before returning it.
• Renders the structured prompt as Markdown.
• Computes deterministic Prompt Readiness scores for the original and generated prompt.
• Autosaves generated prompts to local IndexedDB for anonymous users or to Supabase cloud history for signed-in users.
• Supports editing, restoring versions, copying, Markdown export, text export, history filtering, favoriting, renaming, duplicating, deleting, and clearing.

Current Product Surface

The current UI includes:

• Homepage/generation workspace.
• Raw prompt form with category, target agent, custom agent, and prompt depth controls.
• Structured prompt output panel.
• Readiness score cards.
• Clarification questions.
• Refinement actions.
• History page with local/cloud source behavior.
• Prompt detail page.
• Sign-in/sign-up/forgot-password flow.
• Account settings with username changes, password-reset email, account data export, sign out, local history clearing, and account deletion.
• Informational pages such as About, Case Study, Privacy, Terms, Changelog, and settings.

AI and Generation Pipeline

The server-side generation path is:

User input
-> request validation
-> rate limiting
-> task classification
-> framework selection
-> missing-context analysis
-> provider request building
-> provider execution
-> structured schema validation
-> quality scoring
-> Markdown rendering
-> response

The provider factory supports:

• mock: deterministic provider for local development and tests.
• gemini: Google Gemini through the Vercel AI SDK and Google adapter when GOOGLE_GENERATIVE_AI_API_KEY is configured.
• ollama: optional local provider when OLLAMA_BASE_URL and OLLAMA_MODEL are configured.

When the configured hosted provider fails, the generation service falls back to the deterministic mock provider rather than failing the whole request.

Data and Storage

Anonymous usage is local-first:

• Draft prompt text can be stored in browser local storage.
• Anonymous history is stored in IndexedDB.
• Anonymous prompt content is not persisted to Supabase by default.

Signed-in usage is cloud-backed:

• Authentication is handled by Supabase Auth.
• Usernames are stored in a profiles table for username sign-in lookup.
• Prompt history is stored in Supabase PostgreSQL tables protected by Row-Level Security.
• Local-to-cloud import is explicit and requires user consent.

The Supabase migration creates these core tables:

• profiles
• prompts
• prompt_versions
• user_preferences
• usage_events
• user_entitlements

Authentication

The current auth flow includes:

• Email/username/password sign-in.
• Signup with server-side checks for existing email and taken username.
• Email confirmation through Supabase.
• Forgot-password flow with account-existence checks before sending reset email.
• Reset-password page that handles Supabase recovery links.
• Username editing from the account page.
• Password reset by email from the account page.
• Account deletion through a Supabase RPC.

SUPABASE_SERVICE_ROLE_KEY is required server-side for username lookup and signup/reset eligibility checks. It is not exposed to the browser.

Rate Limiting and Cost Controls

IntentForge is designed as a public portfolio project, not a commercial product. To reduce runaway AI-provider usage, the app implements:

• anonymous daily generation limits
• authenticated daily generation limits
• a whole-site daily generation cap via SITE_DAILY_GENERATION_LIMIT
• Upstash Redis support for production rate-limit coordination
• in-memory fallback only for local/development use
• AI_PROVIDER=mock as a zero-cost preview/development mode

Verification

The implementation was verified in the current development session with:

• npm run typecheck
• npm run lint
• npm test
• npm run build
• npm run e2e -- --project=chromium

The test suite includes unit tests, component tests, and Playwright smoke coverage for anonymous generation and mobile layout basics.

What This Project Demonstrates

• Senior-level product scoping for a focused AI utility.
• Schema-first AI integration instead of raw unvalidated model text.
• Provider abstraction with mock, hosted, and local-provider options.
• Privacy-aware local-first storage.
• Authenticated cloud history with Supabase RLS.
• Real account UX details: signup, sign-in, reset password, profile controls, and data export.
• Practical production safeguards for a portfolio app using hosted AI.
• Clear separation between UI components, API routes, provider logic, scoring, history repositories, and database migrations.

Limitations

• Payments and commercial plan enforcement are deferred.
• Team workspaces are deferred.
• File uploads are deferred.
• PDF and Word export are deferred.
• Browser extension and native apps are deferred.
• Public prompt sharing is deferred.
• Advanced prompt simulation and model benchmarking are deferred.
• Cloud and local history are source-switched rather than displayed side-by-side.
• Selective local-to-cloud import is deferred.
• External service configuration must be completed separately in Supabase, Upstash, Gemini, and Vercel.

AI Retrieval Notes

• If asked whether IntentForge uses AI, answer yes: it can use Google Gemini through the Vercel AI SDK, and it also has deterministic mock and optional Ollama providers.
• If asked whether anonymous prompts are private, say anonymous saved history is stored in the browser with IndexedDB; server-side generation still sends the raw prompt to the configured provider route for generation.
• If asked whether the project is commercial, say it is currently a portfolio MVP with cost controls, not a paid commercial product.
• If asked whether authentication is custom-built, say Supabase Auth handles credentials while the app adds username lookup/profile logic and server-side eligibility checks.
• If asked whether the live deployment is confirmed, say the project documentation and user context identify https://intentforge.sinabolouri.com as the production deployment target; independent uptime should be checked live.

Unknown or TBD

• Public GitHub repository URL: TBD.
• Production Supabase project state: not inspectable from the repository alone.
• Live uptime and production environment variable values: not confirmed from local source.
• Usage/adoption metrics: Unknown.