MWAP (Modular Web Application Platform) is a fullstack, secure, scalable SaaS framework designed for building dynamic, multi-tenant web applications with robust security and flexibility.
- Runtime: Node.js (v18+)
- Web Framework: Express.js
- Database: MongoDB Atlas (Mongoose ODM)
- Authentication: Auth0 JWT (RS256, JWKS)
- Schema Validation: Zod
- Zero Trust Model: Strict role-based access control
- JWT Authentication with RS256 and JWKS endpoint validation
- Multi-Factor Authentication via Auth0
- Field-Level Encryption in MongoDB
- Rate Limiting on all APIs
- Secure Headers with Helmet
The server is organized around core domain entities:
Tenant: User workspace and logical isolationProject: Application instance with fixed configurationProjectType: Defines application behaviorCloudProvider: Supported cloud storage integrations
/src
/features → Domain-specific logic
/tenants → Tenant management
/projects → Project operations
/cloud-providers → Cloud provider management
/oauth → OAuth 2.0 implementation
/middleware → Authentication and security
/services → Shared business logic
/schemas → Zod schema definitions
/utils → Helper methods
/config → Environment and connection setup
- Multi-tenant architecture
- Dynamic project type configuration
- Enhanced OAuth-based cloud provider integrations
- NEW: OAuth flow initiation endpoint for consistent redirect URI construction
- FIXED: Dropbox OAuth redirect URI mismatch errors
- IMPROVED: Express proxy configuration for Heroku environments
- Dedicated OAuth callback endpoint with enhanced security
- Secure token exchange and storage with HTTP Basic Auth
- Standardized OAuth 2.0 flow with provider-specific parameters
- Field-level encryption for sensitive data
- Microservice-friendly design
- Comprehensive audit logging
Full API specification available in /docs/04-Backend/v3-api.md. Key endpoints include:
/api/v1/tenants: Tenant management/api/v1/projects: Project CRUD operations/api/v1/cloud-providers: Cloud integration management/api/v1/oauth/callback: OAuth 2.0 callback handling/api/v1/oauth/tenants/:tenantId/integrations/:integrationId/refresh: Token refresh
This project uses Vitest for unit and service-level testing, aligned with the following principles:
- ✅ Pure ESM support (no CommonJS)
- ✅ Centralized
tests/folder (no co-located tests) - ✅ Simple mocks for MongoDB and Auth0 (no DB containers or test factories)
- ✅ Focused tests for service logic, middleware, and schema validation
vitest.config.tswith globalsetupTests.ts- Code coverage via
vitest run --coverage - Test structure mirrors
/src/features
Comprehensive documentation is organized into 10 main sections:
| Section | Description | Key Documents |
|---|---|---|
| 00-Overview | Project vision, tech stack, and changelog | vision.md, tech-stack.md, changelog.md |
| 01-Getting-Started | Setup, installation, and onboarding | getting-started.md, env-setup.md, DEVELOPER_ONBOARDING.md |
| 02-Architecture | System design and architecture | overview.md, system-design.md, v3-architecture-reference.md |
| 03-Frontend | Frontend development guides | authentication.md, api-integration.md, rbac.md |
| 04-Backend | Backend API and server documentation | express-structure.md, auth0.md, rbac.md, cloud-providers.md |
| 05-AI-Agents | AI agent framework and patterns | microagents.md, openhands-integration.md, prompt-engineering.md |
| 06-Guides | How-to guides and tutorials | how-to-deploy.md, debugging.md, optimization-report.md |
| 07-Standards | Coding standards and conventions | naming.md, commit-style.md, branching.md, development-guide.md |
| 08-Contribution | Contribution guidelines | contributing.md, documentation-guide.md |
| 09-Reports-and-History | Project status and reports | STATUS.md, REORGANIZATION_SUMMARY.md |
- Express Server Structure - Complete server architecture guide
- Auth0 Integration - Authentication implementation
- RBAC Implementation - Role-based access control
- Cloud Provider Patterns - OAuth integration patterns
- Background Jobs - Background processing patterns
- API Configuration - OpenAPI generation and setup
- Development Guide - Complete development workflow
- Environment Setup - Environment variable standards
- Naming Conventions - Codebase naming standards
- Git Workflow - Branching strategy and git conventions
- Commit Style - Commit message standards
- Deployment Guide - Production deployment procedures
- Debugging Guide - Troubleshooting and debugging
- Performance Optimization - Performance tuning strategies
- Auth0 Integration Guide - Complete Auth0 setup
- Microagents - AI agent framework overview
- OpenHands Integration - AI-powered development assistance
- Prompt Engineering - Best practices for AI prompts
- Agent Patterns - Proven agent implementation patterns
- Best Practices - AI agent development guidelines
- How to Add Agents - Step-by-step agent creation guide
The project includes interactive API documentation accessible at /docs when the server is running. This documentation:
- Provides comprehensive overview of all API endpoints
- Includes request/response schemas and authentication requirements
- Supports interactive testing via Swagger UI (when installed)
- Is secured behind authentication to prevent information disclosure
To access the API documentation:
- Start the server:
npm run dev - Navigate to
http://localhost:3001/docs(requires authentication) - For raw OpenAPI specification:
http://localhost:3001/docs/json
Security Note: API documentation is protected by authentication to prevent exposing sensitive system information.
- Node.js (v18 or higher)
- MongoDB Atlas account and connection string
- Auth0 account with application configured
- Git for version control
# Clone the repository
git clone <repository-url>
cd mwapserver
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# Edit .env with your configuration
# Run database migrations (if any)
npm run migrate
# Start development server
npm run dev
# Run tests
npm testSee Environment Setup Guide for detailed configuration instructions.
✅ Core Infrastructure: Complete
✅ Authentication & RBAC: Complete
✅ Cloud Provider Integration: Complete
✅ API Documentation: Complete
✅ Deployment Procedures: Complete
🚧 AI Agents Framework: In Progress
📋 Testing Infrastructure: Planned
For detailed status information, see Project Status.
We welcome contributions! Please read our Contributing Guidelines and follow our Development Standards.
- Read the Development Guide
- Follow Naming Conventions
- Use Git Workflow and Commit Standards
- Test thoroughly using Testing Guide
- Questions? Check the FAQ
- Issues? See Troubleshooting
- Debugging? Use the Debugging Guide
- Deploying? Follow the Deployment Guide
[Insert License Information]
This documentation is maintained as part of the MWAP project. For updates and improvements, see the documentation guide.