Nexus: The Local-First Database Dashboard

Nexus is a local-first, open-source dashboard for developers who juggle multiple projects. Stop logging into five different web UIs—manage all your MongoDB and Supabase databases from one simple, secure, locally-running application.

📖 Read the full case study: Why I Built a Local-First Database Dashboard (and Why You Should Too)

---

Why Nexus?

As a developer, I constantly switch between projects. My "AI App" (PromptCraft) uses MongoDB, while my "AI Partner" (VibeScribe) uses Supabase. I built Nexus because I was tired of the fragmented workflow of logging into multiple, slow web UIs just to check data.

Nexus solves this by being:

• Local-First & Secure: The app runs entirely on your machine. All your credentials are stored in a local-only connections.json file. Nothing ever leaves your computer.
• A Unified Hub: Connect to MongoDB Atlas and Supabase (PostgreSQL) instances and view all your data from a single, clean interface.
• Simple & Focused (MVP): The MVP is strictly read-only. It's built for quick data inspection, not complex database management.
• Open-Source & Extensible: The architecture is designed to be easily extended. Adding support for PlanetScale, Firebase, or local SQLite is the next logical step.

Tech Stack

Nexus is built as two separate local applications that work together:

1. Frontend (UI): Next.js (App Router) + TypeScript + Tailwind CSS v4
2. Local Proxy (Backend): Node.js + Express.js + TypeScript

The Next.js app renders the UI. It sends API requests to the local Express.js proxy, which is the only part of the system that holds credentials and communicates with your external databases.

[Link to Architecture Diagram in /docs]

Getting Started / Local Setup

Prerequisites

• Node.js (v18.x or later)
• npm or yarn

Installation & Running

You will need to run two separate processes in two separate terminals.

1. Run the Local Proxy Server (The "Brain")

# Clone the repository
git clone [https://github.com/](https://github.com/)[YOUR_GITHUB_USERNAME]/nexus.git
cd nexus/proxy

# Install dependencies
npm install

# Run the proxy server
npm run dev
# Server is now running on http://localhost:4001

2. Run the Frontend UI

# In a new terminal, navigate to the frontend directory
cd nexus/frontend

# Install dependencies
npm install

# Run the frontend app
npm run dev
# App is now running on http://localhost:3000
# Open http://localhost:3000 in your browser to use the application.

Usage

1. Add a Connection:

• Click "Add New Connection" from the sidebar.

• Give your connection a friendly name (e.g., "VibeScribe Prod").

• Select the type (MongoDB or Supabase) and enter your credentials.

• Click "Save." The proxy will validate and store the connection in proxy/connections.json.

2. Browse Data:

• Click on your saved connection in the sidebar.

• The main panel will show a list of your tables/collections.

• Click on any table/collection to view its data.

Key Architectural Decisions

Supabase Schema Introspection

A key challenge was discovering a user's Supabase tables. A typical approach of querying information_schema.tables fails, as this is not exposed through the public Supabase Data API.

The correct, robust solution implemented in Nexus is to use the PostgREST OpenAPI introspection endpoint. The proxy server fetches the /rest/v1/ endpoint, parses the returned OpenAPI specification, and extracts the table names from the definitions object. This provides an accurate list of all available tables without requiring elevated database permissions.

Troubleshooting / Quick Recovery

Port 4001 Conflict: If the proxy server fails to start with an EADDRINUSE error, another process is using port 4001.

On Windows:

netstat -ano | findstr :4001
taskkill /PID <PID_NUMBER> /F

On macOS/Linux:

lsof -i :4001
kill -9 <PID>

Tailwind Changes Not Applying: As this project uses Tailwind v4, you may need to clear the Next.js cache for config changes to apply.

rm -rf .next
netstat -ano | findstr :4001
taskkill /PID <PID_NUMBER> /F

On macOS/Linux:

lsof -i :4001
kill -9 <PID>

Tailwind Changes Not Applying: As this project uses Tailwind v4, you may need to clear the Next.js cache for config changes to apply.

rm -rf .next

lsof -i :4001
kill -9 <PID>

Tailwind Changes Not Applying: As this project uses Tailwind v4, you may need to clear the Next.js cache for config changes to apply.

rm -rf .next

• Delete the .next folder in the /frontend directory and restart the dev server.

How to Contribute

This is an open-source project, and contributions are welcome!

The main priority (Post-MVP) is adding CUD (Create, Update, Delete) operations and support for more databases (like PlanetScale or SQLite).

1. Fork the repository.

2. Create a new branch (git checkout -b feature/add-planetscale).

3. Make your changes.

4. Submit a Pull Request with a clear description of your changes.

Made by Dev Sharma.