MDDB Panel - Web Admin Interface

Overview

MDDB Panel is a modern, web-based admin interface for MDDB (Markdown Database). It provides a visual way to browse collections, view documents, filter by metadata, and manage your markdown database without using the command line.

Features

📊 Server Statistics Dashboard

Real-time database statistics
Total documents and revisions count
Database size monitoring
Collections overview

📁 Collection Browser

List all collections with document counts
Quick collection switching
Visual collection organization

📄 Document Management

Browse documents with metadata preview
View full document content
Display rich metadata
Edit documents - Modify content and metadata
Markdown editor with live preview - Split view with real-time rendering
Markdown toolbar - Quick formatting (bold, italic, headings, lists, tables, etc.)
Syntax highlighting - Code blocks with 100+ language support
Templates - Pre-built templates for common document types
Create new documents - Add documents directly from UI
Copy markdown content to clipboard
View document revision information

🌐 API Endpoints Browser

Tabbed view of all HTTP, gRPC, and MCP endpoints
HTTP tab with method badges, paths, descriptions, and auth status icons
gRPC tab with method names and descriptions
MCP tab with all 44 built-in tool names and descriptions
Link to versioned OpenAPI spec on GitHub (auto-detects server version)

🔍 Advanced Filtering

Filter documents by metadata fields
Multiple filter criteria support
Sort by date, key, or custom fields
Ascending/descending order
Configurable result limits

🎨 Modern UI

Clean, responsive design
TailwindCSS styling
Lucide React icons
Smooth animations and transitions
Mobile-friendly interface

Quick Start

Prerequisites

Node.js 24.3 or later
npm 11.4.2 or later
Running MDDB server

Installation

cd services/mddb-panel

npm install

Or use Makefile:

make panel-install

Development

npm run dev

make panel-dev

Access the panel at http://localhost:3000

Production

npm run build

npm start

make panel-build

Panel Modes

MDDB Panel supports two deployment modes controlled by MDDB_PANEL_MODE on the mddbd server:

Internal Mode (Default)

The panel and mddbd run together (same host or Docker network). CORS is enabled on mddbd so the browser can make cross-origin requests directly to the API.

Browser -> Panel (:3000)     -> static files
Browser -> mddbd (:11023)    -> API (with CORS headers)

External Mode

The panel runs as a separate service with its own reverse proxy. All API requests from the browser go through the panel's server, which proxies them to mddbd. No CORS needed.

Browser -> Panel (:3000) /v1/* -> proxy -> mddbd (:11023)
Browser -> Panel (:3000) /*    -> static files

Set on mddbd:

MDDB_PANEL_MODE=external

Set on panel container:

MDDB_SERVER=http://mddbd:11023

External mode is recommended when:

Panel is deployed on a different host than mddbd
You want to avoid CORS headers in API responses
You need a single entry point for both UI and API

Docker Deployment

Using Docker Compose

The easiest way to run MDDB Panel with the server:

docker-compose up -d

Standalone Docker

cd services/mddb-panel
docker build -t mddb-panel .

docker run -d \
  -p 3000:3000 \
  -e MDDB_SERVER=http://mddb-server:11023 \
  --name mddb-panel \
  mddb-panel

Configuration

Environment Variables

Variable	Default	Description
`MDDB_SERVER`	`http://localhost:11023`	mddbd server URL (used by production proxy and dev server)
`PORT`	`3000`	Panel server port

Proxy Configuration

Both development and production servers proxy /v1/* requests to mddbd:

Development: Vite dev server proxy (configured in vite.config.js)
Production: Express reverse proxy (server.js)

Usage Guide

Browsing Collections

View Server Stats: The sidebar shows real-time statistics including total documents, revisions, and database size.
Select Collection: Click on any collection in the sidebar to view its documents.
View Document Count: Each collection shows the number of documents it contains.

Viewing Documents

Document List: After selecting a collection, documents are displayed in a list with:
- Document key
- Language code
- Last updated date
- Metadata preview (first 2 tags)
Open Document: Click on any document to view its full content and metadata.
Document Viewer: Shows:
- Full markdown content
- All metadata fields
- Creation and update timestamps
- Revision number
- Collection name
Copy Content: Use the "Copy" button to copy markdown content to clipboard.

Filtering Documents

Open Filters: Click the "Filters" button in the toolbar.
Add Metadata Filters:
- Enter filter key (e.g., "author")
- Enter filter value (e.g., "John Doe")
- Click "Add Filter"
Configure Sort:
- Choose sort field (Added Date, Updated Date, Key)
- Select order (Ascending/Descending)
Set Limit: Specify maximum number of documents to display (1-1000).
Apply: Click "Apply Filters" to update the document list.
Clear: Use "Clear All" to remove all filters.

Editing Documents

Open Document: Click on a document to view it.
Click Edit: Click the "Edit" button in the document viewer.
Use Markdown Editor:
- Edit Mode: Write markdown in the editor
- Preview Mode: See rendered markdown with syntax highlighting
- Split Mode: Edit and preview side-by-side (default)
- Fullscreen: Toggle fullscreen for better focus
- Toolbar: Quick formatting buttons
  - Headings (H1, H2, H3)
  - Bold, Italic, Strikethrough
  - Inline code
  - Links, Lists (bullet, numbered, tasks)
  - Blockquotes, Tables
- Templates: Choose from pre-built templates
  - Blog Post
  - Documentation
  - README
  - API Documentation
  - Changelog
- Real-time preview with syntax highlighting
- Support for GitHub Flavored Markdown (tables, task lists, etc.)
- Code blocks with 100+ language support
Modify Content:
- Edit markdown content with live preview
- Add, remove, or update metadata fields
- See character, line, and word count
- All changes are tracked
Save Changes: Click "Save Changes" to update the document.
Success: Document is updated and a new revision is created.

Creating New Documents

Select Collection: Choose the collection where you want to add a document.
Click New Document: Click the "New Document" button in the toolbar.
Fill Details:
- Enter unique document key
- Select language
- Add metadata (optional)
- Write markdown content
Create: Click "Create Document" to save.

Keyboard Shortcuts

Esc - Close document viewer, editor, or filter panel
Ctrl/Cmd + C - Copy document content (when viewer is open)
Enter - Add metadata field (when in metadata input)

Architecture

Tech Stack

React 19.1 - Modern UI framework with latest features
Vite 6 - Fast build tool and dev server
TailwindCSS 4 - Utility-first CSS framework
Zustand 5 - Lightweight state management
Lucide React 0.544 - Beautiful icon library
date-fns 4 - Modern date utility library
react-markdown 10 - Markdown rendering component
remark-gfm 4 - GitHub Flavored Markdown support
rehype-raw/sanitize - Safe HTML rendering
react-syntax-highlighter - Code syntax highlighting
prismjs - Syntax highlighting engine (100+ languages)

Project Structure

services/mddb-panel/
├── src/
│   ├── components/
│   │   ├── Header.jsx           # Top navigation bar
│   │   ├── Sidebar.jsx          # Collections and stats
│   │   ├── DocumentList.jsx     # Document browser
│   │   ├── DocumentViewer.jsx   # Document details view
│   │   ├── DocumentEditor.jsx   # Document editing modal
│   │   ├── NewDocumentModal.jsx # New document creation
│   │   ├── MarkdownEditor.jsx   # Markdown editor with preview
│   │   ├── MarkdownToolbar.jsx  # Formatting toolbar
│   │   ├── EndpointsPanel.jsx   # API endpoints browser
│   │   └── FilterPanel.jsx      # Filter controls
│   ├── lib/
│   │   ├── mddb-client.js       # API client
│   │   ├── markdown-templates.js # Document templates
│   │   └── store.js             # Zustand store
│   ├── App.jsx                  # Main application
│   ├── main.jsx                 # Entry point
│   └── index.css                # Global styles
├── public/                      # Static assets
├── index.html                   # HTML template
├── vite.config.js               # Vite configuration
├── tailwind.config.js           # Tailwind configuration
├── postcss.config.js            # PostCSS configuration
├── package.json                 # Dependencies
├── Dockerfile                   # Docker build
└── README.md                    # Panel documentation

State Management

The panel uses Zustand for global state management:

// Global state includes:
- stats              // Server statistics
- currentCollection  // Selected collection
- documents          // Document list
- currentDocument    // Selected document
- filters            // Active filters
- sortBy             // Sort field
- sortAsc            // Sort order
- limit              // Result limit

API Client

The panel communicates with MDDB server via HTTP API:

// Available methods:
- getStats()         // Get server statistics
- search()           // Search documents
- getDocument()      // Get single document
- addDocument()      // Add/update document
- export()           // Export documents
- backup()           // Create backup
- truncate()         // Clean old revisions
- getEndpoints()     // List all API endpoints

API Integration

The panel uses the following MDDB API endpoints:

GET /v1/stats

Get server statistics including document count, database size, and collections.

POST /v1/search

Search documents with filters:

{
  "collection": "blog",
  "filterMeta": {
    "author": ["John Doe"]
  },
  "sort": "updatedAt",
  "asc": false,
  "limit": 100
}

GET /v1/endpoints

Get all available HTTP, gRPC, and MCP endpoints with descriptions and auth status.

POST /v1/get

Get a specific document:

{
  "collection": "blog",
  "key": "hello-world",
  "lang": "en_US"
}

Customization

Styling

The panel uses TailwindCSS for styling. Customize colors in tailwind.config.js:

theme: {
  extend: {
    colors: {
      primary: {
        50: '#f0f9ff',
        // ... customize colors
      },
    },
  },
}

Components

All components are in src/components/ and can be customized:

Header.jsx - Top navigation
Sidebar.jsx - Left sidebar with collections
DocumentList.jsx - Document browser
DocumentViewer.jsx - Document details
FilterPanel.jsx - Filter controls

API Client

Extend the API client in src/lib/mddb-client.js to add new endpoints or functionality.

Performance

Optimization Features

Code Splitting - Vite automatically splits code for faster loading
Tree Shaking - Unused code is removed in production builds
Minification - JavaScript and CSS are minified
Compression - Gzip compression for smaller bundle sizes
Lazy Loading - Components load on demand
Memoization - React components use proper memoization

Build Optimization

npm run build

npm run build -- --mode analyze

Troubleshooting

Panel won't start

Issue: Development server fails to start

Solution:

rm -rf node_modules package-lock.json
npm install

Can't connect to MDDB server

Issue: API requests fail with connection errors

Solution:

Ensure MDDB server is running on port 11023
Check VITE_MDDB_SERVER environment variable
Verify proxy configuration in vite.config.js

Build fails

Issue: Production build fails

Solution:

node --version

npm update

rm -rf dist node_modules
npm install
npm run build

Filters not working

Issue: Filters don't affect document list

Solution:

Click "Apply Filters" after adding filters
Check browser console for errors
Verify MDDB server supports the filter fields

Browser Support

Chrome/Edge 90+
Firefox 88+
Safari 14+
Opera 76+

Security Considerations

Production Deployment

Use HTTPS: Always deploy with HTTPS in production
Environment Variables: Never commit .env files
API Authentication: Consider adding authentication to MDDB server
CORS: Configure CORS properly on MDDB server
Content Security Policy: Add CSP headers

Best Practices

Keep dependencies updated
Use environment variables for configuration
Enable HTTPS for production
Implement proper error handling
Monitor server logs

Contributing

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Code Style

Use functional components with hooks
Follow React best practices
Use TailwindCSS for styling
Keep components small and focused
Add comments for complex logic

Testing

npm run lint

npm run lint -- --fix

Roadmap

Completed Features

[x] Document editing interface
[x] Document creation from UI
[x] Metadata editor
[x] Markdown editor with live preview
[x] Split-view editing (edit/preview/both)
[x] Fullscreen editing mode
[x] GitHub Flavored Markdown support
[x] Markdown toolbar with formatting buttons
[x] Syntax highlighting for code blocks (100+ languages)
[x] Document templates (blog, docs, README, API, changelog)
[x] API Endpoints browser with HTTP/gRPC/MCP tabs
[x] OpenAPI spec link with auto-detected version

Planned Features

[ ] Document deletion
[ ] Bulk operations (delete, export multiple)
[ ] Advanced search with full-text
[ ] Document comparison (diff view)
[ ] Revision history viewer with diff
[ ] User authentication
[ ] Role-based access control
[ ] Dark mode
[ ] More keyboard shortcuts
[ ] Export to various formats (PDF, HTML)
[ ] Import from files (drag & drop)
[ ] Collection management (create, delete)
[ ] Server configuration UI
[ ] More syntax themes (light/dark)
[ ] Custom markdown templates
[ ] Markdown shortcuts (Ctrl+B for bold, etc.)
[ ] Auto-save drafts
[ ] Spell checker

License

BSD 3-Clause License - see LICENSE for details.

Overview

Features

📊 Server Statistics Dashboard

📁 Collection Browser

📄 Document Management

🌐 API Endpoints Browser

🔍 Advanced Filtering

🎨 Modern UI

Quick Start

Prerequisites

Installation

Development

Production

Panel Modes

Internal Mode (Default)

External Mode

Docker Deployment

Using Docker Compose

Standalone Docker

Configuration

Environment Variables

Proxy Configuration

Usage Guide

Browsing Collections

Viewing Documents

Filtering Documents

Editing Documents

Creating New Documents

Keyboard Shortcuts

Architecture

Tech Stack

Project Structure

State Management

API Client

API Integration

GET /v1/stats

POST /v1/search

GET /v1/endpoints

POST /v1/get

Customization

Styling

Components

API Client

Performance

Optimization Features

Build Optimization

Troubleshooting

Panel won't start

Can't connect to MDDB server

Build fails

Filters not working

Browser Support

Security Considerations

Production Deployment

Best Practices

Contributing

Development Workflow

Code Style

Testing

Roadmap

Completed Features

Planned Features

See Also

License