A comprehensive, full-stack web application framework with Next.js, tRPC, Drizzle ORM, WebSocket support, workflow orchestration, and task queue functionality. Built with TypeScript and designed for both browser and CLI clients.
- ✅ Type-safe API with tRPC - End-to-end type safety from client to server
- ✅ Database ORM with Drizzle (PostgreSQL) - Type-safe database queries and schema management
- ✅ Real-time Communication - WebSocket server for bidirectional messaging
- ✅ Background Jobs - Task queue with BullMQ and Redis
- ✅ Workflow Orchestration - Temporal for long-running tasks and complex workflows
- ✅ CLI Client - Command-line interface for API, WebSocket, and workflow operations
- ✅ Authentication - Email/password and LDAP authentication support
- ✅ Project Management - Dashboard with project search and permission requests
- Next.js 15 - React framework with App Router and Turbopack
- TypeScript - Type-safe development
- Tailwind CSS - Utility-first CSS framework
- tRPC - End-to-end type-safe API
- Drizzle ORM - Type-safe PostgreSQL ORM
- WebSocket - Real-time bidirectional communication
- BullMQ - Redis-based task queue
- Temporal - Durable workflow orchestration
- PostgreSQL - Primary database
- Redis - Cache and queue backend
- Node.js 18+
- PostgreSQL 14+
- Redis 7+
- Docker and Docker Compose
- tmux (for manage utility)
- npm or yarn
The manage utility provides a streamlined development experience by orchestrating all services in a unified tmux session.
- Clone and setup:
git clone <repository-url>
cd corestack
npm install- Run the complete setup wizard:
./manage.ts setupThis will:
- Check prerequisites
- Install dependencies
- Initialize environment configuration
- Setup databases
- Create an admin user
- Start all development services:
./manage.ts devThis single command starts all 5 services in tmux:
- Temporal infrastructure (Docker)
- Next.js dev server
- WebSocket server
- BullMQ queue workers
- Temporal worker
- Access the application:
- Web UI: http://localhost:3000
- Temporal UI: http://localhost:8080
Manage Utility Commands:
./manage.ts check # Verify prerequisites
./manage.ts init # Initialize environment
./manage.ts db-setup # Setup databases
./manage.ts createsuperuser # Create admin user
./manage.ts dev # Start all services
./manage.ts dev stop # Stop all services
./manage.ts dev status # Check service status
./manage.ts dev logs # View service logstmux Controls:
Ctrl+Bthen0-4: Switch between service panesCtrl+BthenD: Detach (services keep running)tmux attach -t corestack: Reattach to session
If you prefer to manage services individually:
- Clone and install:
git clone <repository-url>
cd corestack
npm install- Setup environment:
cp .env.example .env
# Edit .env with your configuration- Start services:
# Start PostgreSQL, Redis, and Temporal
docker-compose up -d
# Push database schema
npm run db:push- Run the application (requires 4 terminals):
# Terminal 1 - Next.js app
npm run dev
# Terminal 2 - WebSocket server
npm run ws:server
# Terminal 3 - Queue worker (BullMQ)
npm run queue:worker
# Terminal 4 - Temporal worker
npm run temporal:workerAdditional UIs:
- Temporal UI: http://localhost:8080 - Monitor workflows and task execution
Default credentials: username: root, password: Must-Changed
Comprehensive documentation is available in the docs/ directory:
| Guide | Description |
|---|---|
| Manage Utility Design | Design proposal for the interactive management utility (planned feature) |
| Codebase Exploration | Comprehensive overview of the codebase structure, architecture, and key components |
| Local Development Guide | Step-by-step guide for setting up the project without Docker/Kubernetes |
| Guide | Description | Implementation Status |
|---|---|---|
| Architecture | System architecture and tech stack overview | 🟢 100% Complete |
| API Reference | tRPC endpoints and WebSocket protocol | 🟢 100% Complete |
| Database Guide | Schema overview and Drizzle ORM basics | 🟢 95% Complete* |
| Authentication | Email/password and LDAP authentication | 🟢 100% Complete |
| Development Guide | Development workflow and adding features | 🟢 100% Complete |
| Deployment Guide | Production deployment and scaling | 🟡 60% Complete** |
| WebSocket Guide | Real-time communication setup | 🟢 100% Complete |
| Task Queue Guide | Background job processing (BullMQ) | 🟢 100% Complete |
| Temporal Integration | Workflow orchestration with Temporal | 🟢 100% Complete |
| CLI Guide | Command-line interface usage | 🟢 100% Complete |
| SSH Remote Operations | SSH operations and remote file management | 🟢 100% Complete |
| Bun Adoption* | Bun runtime migration strategy | 🔴 0% Complete |
*Database: Schema complete, migrations not yet generated via drizzle-kit generate
**Deployment: Local Docker setup complete, production CI/CD and monitoring not configured
***Bun Adoption: Design/planning phase only, not yet implemented
Each topic has detailed documentation in subfolders:
- docs/development/ - Codebase exploration and overview guides
- docs/architecture/ - Request flows, WebSocket protocol, job processing
- docs/authentication/ - Login verification, LDAP setup guides
- docs/database/ - Complete schema reference, migration guides
- docs/api/ - Detailed API endpoint documentation
- docs/development/ - Development guides and best practices
- docs/deployment/ - Deployment configurations
- docs/websocket/ - WebSocket implementation details
- docs/task-queue/ - Queue management and workers
- docs/cli/ - CLI command references
./manage.ts setup # Complete setup wizard
./manage.ts check # Check prerequisites
./manage.ts install # Install dependencies
./manage.ts init # Initialize environment
./manage.ts db-setup # Setup databases
./manage.ts createsuperuser # Create admin user
./manage.ts dev # Start all services
./manage.ts dev stop # Stop all services
./manage.ts dev restart # Restart all services
./manage.ts dev status # Check service status
./manage.ts dev logs [service] # View logsnpm run dev # Start Next.js development server
npm run build # Build for production
npm start # Start production server
npm run lint # Run ESLintnpm run db:push # Push schema to database (development)
npm run db:generate # Generate migrations
npm run db:migrate # Run migrations (production)
npm run db:studio # Open Drizzle Studionpm run ws:server # Start WebSocket server
npm run queue:worker # Start BullMQ queue worker
npm run temporal:worker # Start Temporal worker# User management
npm run cli user list # List all users
npm run cli user create "John" "john@example.com" # Create user
# WebSocket
npm run cli ws listen demo # Listen to WebSocket channel
npm run cli ws send demo "Hello!" # Send WebSocket message
# Temporal workflows
npm run cli task start build -p myproject # Start build workflow
npm run cli task status <workflowId> # Get workflow status
npm run cli task status <workflowId> -f # Follow workflow progress
npm run cli task list # List all workflows
npm run cli task cancel <workflowId> # Cancel workflowcorestack/
├── app/ # Next.js app directory
│ ├── api/ # API routes (tRPC, queue)
│ ├── login/ # Login page
│ └── projects/ # Projects dashboard
├── components/ # React components
├── lib/ # Shared libraries
│ ├── auth/ # Authentication
│ ├── db/ # Database & schema
│ ├── trpc/ # tRPC configuration
│ ├── websocket/ # WebSocket client
│ ├── queue/ # Queue configuration
│ └── temporal/ # Temporal client & config
├── server/ # Server-side code
│ ├── routers/ # tRPC routers
│ ├── queue/ # BullMQ workers
│ ├── temporal/ # Temporal workflows & workers
│ │ ├── workflows/ # Workflow definitions
│ │ ├── activities/ # Activity implementations
│ │ └── workers/ # Worker configurations
│ └── websocket.ts # WebSocket server
├── cli/ # CLI client
├── docs/ # Documentation
└── scripts/ # Utility scripts
Required environment variables (see .env.example):
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mydb
REDIS_URL=redis://localhost:6379
TEMPORAL_ADDRESS=localhost:7233
TEMPORAL_NAMESPACE=default
PORT=3000
WS_PORT=3001
NODE_ENV=development
JWT_SECRET=your-secret-keyOptional LDAP configuration:
LDAP_URL=ldap://your-ldap-server:389
LDAP_BIND_DN=cn=admin,dc=example,dc=com
LDAP_BIND_PASSWORD=password
LDAP_SEARCH_BASE=ou=users,dc=example,dc=com- Fork the repository
- Create a feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request
MIT
For issues and questions, please open an issue on GitHub.