Next.js Application with Multi-Database Support

A production-ready Next.js 16 application with database management capabilities, built with TypeScript, Tailwind CSS, and DrizzleORM for connecting to multiple database backends.

🏗️ Configuration-Driven Architecture

This project features a unique JSON-driven architecture that makes adding features incredibly simple:

• Define features in JSON (src/config/features.json) - no need to write boilerplate code
• Automatic UI generation - navigation and forms are generated by looping over configuration
• Reusable components - shared DataGrid, FormDialog, and ConfirmDialog components
• Feature flags - enable/disable features with a single boolean in the config
• Type-safe - TypeScript ensures configuration integrity

Example: To add a new feature, simply add an entry to features.json:

{
  "id": "my-feature",
  "name": "My Feature",
  "enabled": true,
  "endpoints": [...],
  "ui": { "showInNav": true, "icon": "Star", "actions": ["create", "read"] }
}

The system automatically generates the navigation item, API routes, and UI components!

Overview

This project is a full-stack web application featuring:

• Next.js 16 with App Router for server-side rendering and static site generation
• Configuration-driven architecture - Features defined in JSON, UI generated automatically
• Database CRUD operations - Create, read, update, and delete records through a clean UI
• DrizzleORM for type-safe database operations with support for PostgreSQL, MySQL, and SQLite
• PostgreSQL 15 included as default database in Docker container
• Multi-database support - Connect to external PostgreSQL, MySQL, or SQLite servers
• Admin panel with authentication, table management, and SQL query interface
• Authentication using JWT with secure session management
• TypeScript for type safety across the entire stack
• Tailwind CSS 4 for modern, responsive styling
• Docker support for easy deployment
• Comprehensive testing with Vitest, Playwright, and Storybook

Features

• ⚡ Next.js 16 with App Router support
• 🏗️ Configuration-Driven Architecture - Define features in JSON, auto-generate UI
• 🔥 TypeScript for type safety
• 💎 Tailwind CSS 4 for styling
• 🗄️ Database CRUD Operations - Full Create, Read, Update, Delete functionality
• 🛠️ Admin Panel - Manage tables, columns, and data through a beautiful UI
• 📊 SQL Query Interface - Execute custom queries with safety validation
• 🔒 JWT Authentication with secure session management
• 📦 DrizzleORM - Support for PostgreSQL, MySQL, and SQLite
• 🔌 Multi-Database Support - Connect to custom database servers
• 🐳 Docker with included PostgreSQL 15 (default option)
• ♻️ Reusable Components - DataGrid, FormDialog, ConfirmDialog for consistent UX
• 🧪 Testing Suite - Vitest for unit tests, Playwright for E2E
• 🎨 Storybook for UI component development
• 📏 ESLint & Prettier for code quality
• 🔍 TypeScript strict mode
• 🌐 Multi-language (i18n) support with next-intl
• 🚨 Error Monitoring with Sentry
• 🔐 Security with Arcjet (bot detection, rate limiting)

Quick Start

Prerequisites

• Node.js 20+ and npm
• Docker (optional, for containerized deployment)

Local Development

1. Clone the repository:

git clone https://github.com/johndoe6345789/postgres.git
cd postgres

2. Install dependencies:

npm install

3. Set up environment variables: Create a .env.local file:

# Database
DATABASE_URL=postgresql://docker:docker@localhost:5432/postgres

# JWT Secret (required for admin authentication)
JWT_SECRET=your_secure_random_secret_here

# Optional: Admin user creation
CREATE_ADMIN_USER=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=admin123

# Optional: Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_key
CLERK_SECRET_KEY=your_secret

4. Run the development server:

npm run dev

5. Open http://localhost:3000 in your browser.

Admin Panel

Access the admin panel at http://localhost:3000/admin/login

Default credentials (if using db:seed-admin):

• Username: admin
• Password: admin123 (change this in production!)

Features available in the admin panel:

• 📊 Table Browser: View all database tables and their data
• ✏️ CRUD Operations: Create, edit, and delete records
• 🔍 SQL Query Interface: Execute custom SELECT queries
• 🛠️ Schema Inspector: View table structures, columns, and relationships
• 🔐 Secure Access: JWT-based authentication with session management

Docker Deployment

The Docker container includes PostgreSQL 15 as the default database option. You can also connect to external database servers.

Build and run with included PostgreSQL:

docker build -t postgres-app .
docker run -p 3000:3000 -p 5432:5432 \
  -e JWT_SECRET=your_secret_here \
  postgres-app

Or connect to an external database:

docker run -p 3000:3000 \
  -e DATABASE_URL="postgresql://username:password@your-external-db:5432/mydb" \
  -e JWT_SECRET=your_secret_here \
  postgres-app

The Docker container includes both PostgreSQL and the Next.js application, but PostgreSQL is optional - you can connect to any external PostgreSQL, MySQL, or SQLite database.

Project Structure

├── src/
│   ├── app/              # Next.js App Router pages
│   │   ├── admin/        # Admin panel pages (dashboard, login)
│   │   └── api/admin/    # Admin API routes (CRUD, tables, queries)
│   ├── components/       # React components
│   │   └── admin/        # Reusable admin components (DataGrid, FormDialog, etc.)
│   ├── config/           # Configuration files
│   │   └── features.json # Feature definitions (JSON-driven architecture)
│   ├── models/           # Database models (DrizzleORM schemas)
│   ├── utils/            # Utility functions
│   │   ├── featureConfig.ts  # Feature configuration loader
│   │   ├── db.ts         # Database connection
│   │   └── session.ts    # JWT session management
│   ├── libs/             # Third-party library configurations
│   └── locales/          # i18n translations
├── tests/
│   ├── integration/      # Integration tests
│   └── e2e/              # End-to-end tests
├── migrations/           # Database migrations
├── public/               # Static assets
├── Dockerfile            # Docker configuration
└── docker-compose.yml    # Docker Compose setup

Configuration-Driven Features

Adding a New Feature

To add a new feature to the admin panel:

1. Define the feature in src/config/features.json:

{
  "id": "my-new-feature",
  "name": "My New Feature",
  "description": "Description of what it does",
  "enabled": true,
  "priority": "high",
  "endpoints": [
    {
      "path": "/api/admin/my-feature",
      "methods": ["GET", "POST"],
      "description": "API endpoint description"
    }
  ],
  "ui": {
    "showInNav": true,
    "icon": "Settings",
    "actions": ["create", "read", "update", "delete"]
  }
}

2. Add navigation item to navItems array (if needed):

{
  "id": "my-feature",
  "label": "My Feature",
  "icon": "Settings",
  "featureId": "my-new-feature"
}

3. Create API route at src/app/api/admin/my-feature/route.ts

4. The UI is automatically generated from your configuration!

Reusable Components

Use these components for consistent UX:

• <DataGrid> - Display table data with edit/delete actions
• <FormDialog> - Create/edit forms with automatic field generation
• <ConfirmDialog> - Confirmation dialogs for destructive actions

Example:

import DataGrid from '@/components/admin/DataGrid';

<DataGrid
  columns={[{ name: 'id' }, { name: 'name' }]}
  rows={data}
  onEdit={(row) => handleEdit(row)}
  onDelete={(row) => handleDelete(row)}
/>

Available Scripts

Development

• npm run dev - Start development server with live reload
• npm run build - Build production bundle
• npm run start - Start production server
• npm run build-local - Build with local database

Database

• npm run db:generate - Generate database migrations
• npm run db:migrate - Apply database migrations
• npm run db:studio - Open Drizzle Studio (database GUI)
• npm run db:seed-admin - Seed admin user

Testing

• npm run test - Run unit tests
• npm run test:e2e - Run end-to-end tests
• npm run storybook - Start Storybook for component development

Code Quality

• npm run lint - Run ESLint
• npm run lint:fix - Fix linting issues automatically
• npm run check:types - Type check with TypeScript
• npm run check:deps - Check for unused dependencies
• npm run check:i18n - Validate translations

Utilities

• npm run commit - Interactive commit message generator (Conventional Commits)
• npm run generate:password - Generate secure passwords

Database Schema

This application uses DrizzleORM which supports multiple database backends:

• PostgreSQL (default, included in Docker container)
• MySQL/MariaDB (connect to external server)
• SQLite (for local development)

Database schemas are defined in src/models/Schema.ts using DrizzleORM. To modify the schema:

1. Edit src/models/Schema.ts
2. Generate migration: npm run db:generate
3. Apply migration: npm run db:migrate

Connecting to Different Databases

The included PostgreSQL in Docker is just the default option. You can connect to any database by setting the DATABASE_URL environment variable:

PostgreSQL:

DATABASE_URL=postgresql://username:password@localhost:5432/mydb

MySQL:

DATABASE_URL=mysql://username:password@localhost:3306/mydb

SQLite:

DATABASE_URL=file:./local.db

Authentication

This project includes a JWT-based admin authentication system with secure session management:

• Admin Login: Username/password authentication at /admin/login
• Session Management: JWT tokens stored in HTTP-only cookies
• Protected Routes: Admin API endpoints require valid session
• Secure: bcrypt password hashing, 24-hour session expiration

Admin User Setup

Create an admin user by running:

npm run db:seed-admin

Or set environment variables for automatic creation on startup:

CREATE_ADMIN_USER=true
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_secure_password
JWT_SECRET=your_jwt_secret_here

Clerk Integration (Optional)

The project also supports Clerk for additional authentication options:

1. Create a Clerk account and application
2. Copy your API keys to .env.local:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
CLERK_SECRET_KEY=sk_...

Features include:

• Email/password authentication
• Social login (Google, GitHub, etc.)
• Multi-factor authentication (MFA)
• User management dashboard

Testing

Unit Tests

Run unit tests with Vitest:

npm run test

Unit tests are located alongside source files with .test.ts or .test.tsx extensions.

E2E Tests

Run end-to-end tests with Playwright:

npx playwright install  # First time only
npm run test:e2e

E2E tests are in the tests/e2e directory with .e2e.ts extensions.

Component Development

Use Storybook for isolated component development:

npm run storybook

Deployment

Environment Variables

Required environment variables for production:

• DATABASE_URL - PostgreSQL connection string
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY - Clerk public key
• CLERK_SECRET_KEY - Clerk secret key
• JWT_SECRET - Secret for JWT token signing
• NODE_ENV=production

Optional:

• CREATE_ADMIN_USER - Set to true to create admin user on startup
• ADMIN_USERNAME - Admin username (default: admin)
• ADMIN_PASSWORD - Admin password (default: admin123)

Docker

The application can be deployed using the included Dockerfile:

# Build image
docker build -t postgres-app .

# Run container
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://..." \
  -e CLERK_SECRET_KEY="sk_..." \
  -e NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_..." \
  -e JWT_SECRET="your-secret" \
  postgres-app

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using conventional commits (npm run commit)
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

This project follows Conventional Commits. Use the interactive commit tool:

npm run commit

Roadmap

See ROADMAP.md for planned features and improvements.

License

Licensed under the MIT License. See LICENSE for more information.

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.