The AI Orchestrator

Why I Built a Local-First Database Dashboard (And Why You Should Too)

Dev Sharma — Sat, 08 Nov 2025 20:47:56 GMT

The Problem: My Data Lived in 10 Different Tabs

As an AI Application Developer, I'm constantly building and managing multiple projects. My PromptCraft project , which required a per-user, database-driven quota system, runs on MongoDB. My VibeScribe V2 project , an 'AI Partner' with deep personalization, runs on Supabase (PostgreSQL).

This created a massive, daily friction.

Every time I needed to debug an issue, I had to:

Stop coding.
Open a new browser tab for MongoDB Atlas. Log in. Find the project. Find the cluster. Find the collection.
Open another browser tab for Supabase. Log in. Find the project. Find the table.
Try to compare data between two completely different, slow, web-based UIs.

My workflow was fragmented. The context-switching was killing my productivity. I didn't need a heavy, all-in-one cloud platform—I just needed visibility.

So, I decided to architect a solution from the ground up: Nexus, a 100% local-first, open-source dashboard that unifies all my databases into one simple, fast, and secure interface.

This article isn't just a "show and tell." It's a deep dive into the "why" of the architecture, the "how" of the implementation, and the critical, real-world "gotchas" I hit and solved along the way.

Chapter 1: The Philosophy — Local-First and Secure

Before writing a line of code, I set two core principles:

Local-First: This tool must run entirely on my machine. It's a local tool for local development. It will not be deployed. This eliminates network latency, and it means I'm not dependent on a third-party service just to see my own data.
Secure: This was non-negotiable. Database credentials (connection strings, API keys) must never live in the browser, and never be accidentally committed to Git.

These two principles dictated the entire system architecture. A simple Next.js app was out of the question—you can't put a MongoClient connection string in a React component without it being exposed in the browser's JavaScript bundle.

The solution had to be a dual-server system.

Chapter 2: The Blueprint — A Dual-Server Architecture

The entire Nexus system is comprised of two separate, local-only applications that run concurrently on your machine.

The Frontend (The "Face"): A Next.js (App Router) + TypeScript + Tailwind v4 app running on http://localhost:3000. This app is "dumb" on purpose. Its only job is to render the UI. It holds no credentials and no sensitive state.
The Local Proxy (The "Brain"): A Node.js + Express.js + TypeScript server running on http://localhost:4001. This server is the "brain" of the operation. It is the only part of the system that holds credentials and communicates with the external databases.

Here is the flow of a single data request:

I click the "VibeScribe" (Supabase) connection in the Next.js UI in my browser.
The Next.js app makes a fetch request, not to Supabase, but to http://localhost:4001/api/data/conn-uuid-123/schemas.
The Local Proxy Server, running on port 4001, receives this request.
It consults its secure, local connections.json file to find the real credentials for conn-uuid-123.
It uses the Supabase driver to query the real Supabase API.
It gets the data, sanitizes it, and sends a clean JSON response back to the Next.js frontend.
The UI simply renders the JSON it receives.

This model is secure because the browser (port 3000) is sandboxed from the credentials (port 4001). We enforce this with a strict CORS policy on the Express server, which only accepts requests from http://localhost:3000.

Chapter 3: Deep Dive — Building The "Brain" (The Proxy)

The real "orchestration" happens in the proxy.

1. Secure Credential Storage

I couldn't use a .env file. A .env is static, and I needed users (me) to be able to add and remove databases from the UI.

The solution is a connections.json file stored in the proxy's root directory. This file is the first line in my .gitignore.

When a user adds a new connection, the UI POSTs the credentials to the proxy. The proxy validates them by attempting a connection, and if successful, reads connections.json, adds the new entry, and writes the file back to disk.

2. The Abstraction Layer

How do you make a UI that treats MongoDB (NoSQL) and Supabase (PostgreSQL) as the same thing? You need an abstraction layer.

I created a dbManager.ts file that acts as a factory. Its job is to build a "service" that conforms to a single, standardized TypeScript interface:

// src/types/index.ts (Simplified)
interface IDatabaseService {
  testConnection(): Promise<boolean>;
  getSchemas(): Promise<{ name: string }[]>; // "Schemas" = Collections or Tables
  getData(
    schemaName: string,
    page: number,
    limit: number
  ): Promise<{ data: any[], total: number }>;
}

Then, I created two classes that implement this interface:

MongoService implements IDatabaseService
SupabaseService implements IDatabaseService

The MongoService.getSchemas() function connects to the cluster and calls db.listCollections(). The SupabaseService.getSchemas() function... well, that's where I hit my first major roadblock.

Chapter 4: The "Gotchas" — Where The Plan Met Reality

No project survives contact with the enemy. My build report summary shows a few critical moments where my initial plan was just wrong.

Gotcha #1: Tailwind v4 is Not v3

This was a classic papercut. The code-gen AI built the UI using Tailwind v3 syntax (@tailwind base; in globals.css). It failed immediately.

The Fix: Tailwind v4 (at the time of this build) requires a new CSS-first approach. I had to rip out the old globals.css and replace it with:

/* frontend/globals.css */
@import "tailwindcss";

@theme {
  --color-dark-900: #121212;
  --color-dark-800: #1e1e1e;
  --color-accent-green: #00f0a0;
  /* ... more theme colors */
}

And in layout.tsx, I had to set className="dark" on the tag to activate dark mode. A simple fix, but a frustrating "new version" hurdle.

Gotcha #2 (The Big One): You Can't "Just Query" Supabase

My original plan for SupabaseService.getSchemas() was to run a simple SQL query: SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'.

It failed. Every single time.

The Root Cause: The public anon key—which is what the user provides and what we should be using for read-only access—is (rightfully) locked down. It does not have permission to query the database's internal information_schema. This is a good security feature by Supabase, but it broke my entire plan.

The Solution: After digging through PostgREST documentation, I found the real way. Supabase's REST API provides an OpenAPI introspection endpoint by default.

The new getSchemas() function in supabaseService.ts now does this instead:

It ignores SQL entirely.
It makes a fetch request to the project's own REST endpoint: https://[PROJECT_URL]/rest/v1/.
This URL returns a massive OpenAPI specification JSON.
This JSON contains a definitions object, and the keys of that object are... the names of all the public tables!
All I had to do was parse the JSON and return Object.keys(openApiSpec.definitions || {}).

This was a massive win. It's more secure, requires no elevated permissions, and is the "Supabase-native" way to get the schema. This is the kind of technical debugging I love.

Chapter 5: The Result and The Future

With the Supabase bug squashed, the app was fully operational. The final GIF shows the entire value loop in 10 seconds:

Add a new Supabase connection.
Click the connection to see the tables (users, content_requests).
Click a table to see the paginated data.
Click "View JSON" to inspect a single row.

It solves my core problem.

But this is just a (very solid) MVP. The "out of scope" list is where this project gets really exciting. The Post-MVP roadmap includes:

P1: CUD Operations: Adding "Create, Update, Delete" functionality. This is complex, as it requires a standardized "data editor" UI that can handle both schemaless MongoDB documents and rigid PostgreSQL rows.
P2: Simple Querying: Adding a filter bar to run simple find() or WHERE queries.
P3: More Databases: The abstraction layer is built. We can now add new services for PlanetScale (MySQL), Firebase, or even local SQLite files.

This is Why We Build

"Nexus" is more than just a personal tool. It's a statement that a simple, secure, and thoughtfully architected local solution is often far more powerful than a bloated, slow, cloud-based one.

It was a fantastic exercise in system design, API abstraction, and debugging. As an "AI Orchestrator," my core expertise is in architecting and building AI-powered apps from the ground up, and this project put those skills to the test in a new domain.

The entire project is open-source. I'd be thrilled if you checked it out, forked it, or contributed to the roadmap.

GitHub Repo: https://github.com/AegisX-dev/Nexus

Connect with me on LinkedIn: https://www.linkedin.com/in/dev-sharma-aegis/

Thanks for reading!

From AI Tool to AI Partner: Re-architecting VibeScribe for Deep Personalization

Dev Sharma — Fri, 07 Nov 2025 11:11:27 GMT

The "Impersonal" Ceiling: VibeScribe V1

Every project starts with a simple idea. For VibeScribe, it was "turn messy ideas into social media posts." V1 did this well. It was a functional MVP: users could dump their thoughts, pick a tone, and get 6 platform-specific posts.

But it had a critical, foundational flaw.

The "Personalization Box" was just a "pre-fill" form. It saved users from re-typing their usernames, but it didn't inform the AI. The AI had no idea who it was writing for. The result? The content was generic, "formulaic," and lacked a unique human voice.

It was an AI Tool, but it wasn't an AI Partner. I knew that for V2, this had to change.

The V2 Vision: "What if the AI could really sound like me?"

The V2 vision was built on one goal: Deep Personalization. I wanted the AI to write from my perspective, understand my projects, and speak to my audience.

My first architectural hypothesis was that this would require a complex RAG (Retrieval-Augmented Generation) pipeline, vector databases, and all the overhead that comes with it.

Then, the game changed.

The release of Google's Gemini 2.5 Flash offered a 1-million-token context window. This unlocked a new, far more elegant architectural strategy: "Context Stuffing."

Why build a complex, slow, and expensive RAG system when I could simply pass the entire user persona directly to the AI in a single, massive prompt? This was the V2 "Aha!" moment. The new architecture would be built on this premise.

My "Secret Weapon": The AI Orchestration Workflow

I don't just "prompt" an AI; I orchestrate a team of AIs, with me as the human-in-the-loop. To manage a complex migration like this, I used my "AI Orchestration" workflow.

It's a 3-role model:

The Orchestrator (Me): The CEO and Human-in-the-Loop. The visionary, the QA, and the final decision-maker.
The Catalyst (My AI Co-Founder): The CPO/CTO. My strategic partner for architecting the product, the database, and the prompts.
The Coder (VS Code Copilot): My hands-on engineering team, executing on the architectural plans I orchestrate.

The most critical step in this workflow is "Phase 2: Priming." Before writing a single line of V2 code, my Catalyst and I updated our README.md to be the "master blueprint" for the entire project. In a fast-moving AI build, this document was our single source of truth, keeping the entire system—human and AI—on track.

The Build: Architecting the V2 "Persona Prompt"

With the strategy set and the blueprint primed, it was time to build. The entire V2 system hinges on three new components.

1. The "Control Panel" (The Frontend): First, I rebuilt the PersonalizationBox.tsx component. It's no longer a simple form; it's the control panel for the user's AI persona, featuring 10 distinct fields.

(**Orchestrator Note: Insert a screenshot of your new 10-field PersonalizationBox here.)

2. The "Nerve Center" (The Backend): Next, I refactored the backend api/generate/route.ts to build a dynamic "Persona Prompt." This buildSystemPrompt function is the core of V2.

(**Orchestrator Note: Embed the code snippet for your buildSystemPrompt function here. Explain how it dynamically adds the "Persona Profile" section.)

3. The "Magic Trick" (Style Mimicking): Finally, I implemented the source_url feature. This allows VibeScribe to fetch content from a user's blog (like my Hashnode articles), strip the HTML, and pass the text to Gemini as a "Source of Truth," with a critical instruction: "mimic this writing style."

The Outcome: A Side-by-Side Comparison

So, did it work? The results speak for themselves. I took the exact same brain dump ("just finished a new blog post on React Server Components") and ran it through all three modes.

V1 (Generic): "Check out this new blog post about React Server Components! #React #WebDev"
V2 (Persona-Aware): (Using my profile: "AI Founder") "As an AI Founder, I'm constantly exploring new tech. My latest post on React Server Components is live. Here's why I believe it's the future for building smart, fast applications..."
V2 (Style-Mimicked): (Using my Hashnode blog) [Show the actual output here. It should use your specific vocabulary, tone, and sentence structure. This is the "wow" moment.]

This is the difference between a generic tool and a true AI partner.

Conclusion & The Future

VibeScribe V2 successfully made the leap. By leveraging a state-of-the-art model (Gemini 2.5 Flash) and a human-centric "AI Orchestration" workflow, we built an AI that doesn't just write for you, but writes as you.

This, I believe, is the new standard for AI applications—not just "smart," but "personalized" in a way that feels genuinely human.

The project has been a massive success in proving the workflow. But VibeScribe is just getting started. It's mastered short-form... now, we're looking at long-form blog and newsletter generation.

Try VibeScribe V2: https://vibe-scribe.vercel.app

See the full V2 architecture on GitHub: https://github.com/AegisX-dev/VibeScribe

Thanks for reading!

How I Built a "Smart" AI Prompt Refiner on a $0 Budget (NEXT.js, Gemini, and a Dual-AI Router)

Dev Sharma — Wed, 05 Nov 2025 19:10:11 GMT

As a MERN stack developer, I've been fascinated by the power of AI code assistants. But I kept hitting a wall.

We've all been there: you have a great idea, so you ask your AI, "Hey, build me a MERN pet store website."

The response is always a useless, generic guide.

This is a failure of context. The AI doesn't know my stack, my goals, or my database. It can't really help. I built PromptCraft to solve this problem for myself.

It's an open-source tool that acts as an 'AI Strategic Co-Founder.' It turns my vague ideas into the expert-level meta-prompts I actually need to get my work done.

The "Aha!" Moment: Pivoting to the Meta-Prompt

My first idea was just a library of individual prompts. But this didn't solve the real problem: the AI still loses context between each step.

The real breakthrough came when I realized the goal wasn't to create a list of prompts, but a single, structured "meta-prompt."

I needed a tool that would generate a full "Project Blueprint"—with the core mission, tech stack, and database schemas—that I could give to my AI all at once. This one prompt would serve as the "brain" for the entire project.

My $0-Budget Architecture (The "How")

The biggest constraint for this project was my core rule: it had to run on a $0 budget. This forced me to think creatively and build a resilient, multi-model system from scratch.

Here’s the architecture I designed.

1. The Dual-Model AI Router

I couldn't rely on just one free API. A single API might go down, change its pricing, or be too slow. The solution was to build an "AI Router" in my NEXT.js backend with two distinct tiers:

The "Basic" Tier: This is for simple, fast prompt rewrites. For this, I used OpenRouter to access a fast and reliable free-tier model (meta-llama/llama-3.2-3b-instruct:free). It's the high-speed, high-availability "workhorse" of the app.
The "Pro" Tier: This is for the heavy-lifting, "Strategic Co-Founder" meta-prompts. For this, I used the Gemini API. It's incredibly powerful at the kind of complex reasoning and structured-text generation I needed for the "Project Blueprint" feature.

2. The Per-User Quota System

Both of these APIs have free-tier rate limits. If just one or two users spammed the "Pro" button, the app would die for everyone else for 24 hours.

To solve this, I built the entire application on next-auth and MongoDB. This system is the core of the app's "nervous system":

On Register: When a new user signs up, their User document is created in MongoDB with two new fields: basicRefinesRemaining: 25 and proRefinesRemaining: 5.
On Login: When that user logs in, the next-auth "session" callback fetches these numbers from the database and injects them securely into the user's session token.
On the Frontend: A global React Context (QuotaContext) reads these values from the session. This makes the quotas available to any component. This is how the Navbar and the "Refine" button instantly know how many refines you have left.
On API Call: This is the most critical step. When a user clicks "Refine," the handleRefine function calls my backend API (e.g., /api/refine/pro). That API route first checks the user's quota in the database.
- If the quota is > 0, it makes the call to the Gemini API, decrements the count in MongoDB, and returns the AI's response.
- If the quota is 0, it immediately returns a 402 'Quota Exceeded' error, saving me money and keeping the app stable.

This simple system makes the app resilient, prevents abuse, and guarantees it will always stay within my $0 budget.

Bugs I Crushed (Proof I Can Solve Problems)

This project wasn't a smooth ride. I hit two major, project-killing bugs that forced me to think beyond the code and debug the entire system.

1. The "Mysterious Token" Bug

When I first wired up my "Basic Refiner," my API calls to the Mistral model started returning a single, useless ~~token.~~

The Problem: The model was "choking" on my prompt. I was trying to force a complex set of instructions into the user role, and the model's output was failing, showing only its internal "start of sequence" token.

The Solution: This required a two-part fix:

Model Pivot: I switched from the Mistral model to a more stable and reliable free-tier model on OpenRouter: meta-llama/llama-3.2-3b-instruct:free.

String Cleaning: I made my API backend more robust. I added a simple string-cleaning function that explicitly removes special tokens like ~~and [INST] from the AI's response before it ever gets sent back to the frontend.~~

This taught me that "AI integration" isn't just about the prompt; it's about model selection and robust data sanitization.

2. The 404 "Works on My Machine" Deployment Error

This was the most frustrating bug. After completing the app, I deployed it to Vercel. The site loaded, login worked... but both "Refine" buttons returned a 404 Not Found error.

It worked perfectly on my local machine. Why not in production?

The Problem: I missed two critical deployment steps.

Environment Variables: My .env.local file (with my GEMINI_API_KEY, etc.) wasn't on GitHub, so Vercel couldn't see it. The API routes were failing to build silently, so the endpoints never "existed" on the server.

File Path Casing: Even after I added the variables, the 404s continued. The final culprit? My local Windows machine didn't care about app/api/Refine (with a capital R), but the production Linux server demanded the 100% lowercase app/api/refine that my code was calling.

The Solution: I had to systematically debug the deployment. I added my env variables to the Vercel project settings and meticulously checked every folder in my repo for case-sensitivity errors.

This bug was a painful but invaluable lesson in deployment that I will never forget.

Conclusion & What's Next

Building PromptCraft was an incredible journey. It started as a simple solution to a personal frustration and grew into a full-stack application that forced me to think as an architect, a product manager, and a QA engineer.

My biggest takeaway is that our job as "AI Orchestrators" isn't just to write code; it's to design the systems that allow AI to help us build better and faster. This project taught me how to manage costs, build a resilient backend, and solve the real-world bugs that happen when code leaves a local machine.

I'm thrilled with how it turned out, and I hope this case study was a helpful look into my process.

You can try the live demo here: 🚀 Live Demo: https://prompt-craft-beryl.vercel.app/

The full open-source code is on GitHub. If you find the project or the architecture interesting, a star (⭐) would mean the world to me. ⭐ GitHub Repo: https://github.com/AegisX-dev/PromptCraft

Thanks for reading!