Multi-Tenant Workspace Management System

A modern, scalable multi-tenant workspace management system built with Next.js 15, AWS DynamoDB, S3, and shadcn/ui. Perfect for organizations that need isolated workspaces for different teams or clients with secure file management capabilities.

✨ Features

🔐 Authentication & Security

• Custom username/password authentication system
• Secure password hashing with bcrypt (12 rounds)
• Complete user data isolation
• Session-based authentication with React Context

🏢 Multi-Tenant Architecture

• Users can create multiple isolated workspaces
• Workspaces contain multiple projects
• Projects manage files with secure access control
• Hierarchical permission system ensuring data isolation

📁 File Management

• Secure file uploads to AWS S3
• Pre-signed URLs for secure downloads (1-hour expiry)
• File size and count limitations
• Organized file structure: users/{userId}/workspaces/{workspaceId}/projects/{projectId}/{fileName}

⚙️ Configurable Limits

• Workspaces per user: 10 (configurable)
• Projects per workspace: 10 (configurable)
• Files per project: 5 (configurable)
• File size limit: 2MB per file (configurable)
• Easy configuration via src/config/global-config.ts

🎨 Modern UI/UX

• Responsive design built with Tailwind CSS
• shadcn/ui components for consistent, accessible design system
• Beautiful, customizable UI components (buttons, cards, dialogs, forms)
• Real-time limit indicators in the UI
• Loading states and error handling
• Intuitive breadcrumb navigation
• Dark/light mode compatible design tokens

🧪 Test Suite Excellence

This project features a comprehensive, production-ready test suite that ensures reliability and maintainability:

Test Coverage Highlights

• 100% Test Suite Success Rate: All 10 test suites passing
• 61 Individual Tests: Complete coverage of all functionality
• 6 Snapshot Tests: UI consistency verification
• Zero Test Failures: Robust, reliable test implementation

Advanced Testing Features

• Web API Polyfills: Custom mocks for Next.js API route testing
• AWS Service Mocking: Complete isolation from external dependencies
• User-Centric Testing: Focus on user interactions and behavior
• Error Scenario Coverage: Comprehensive error handling validation
• Accessibility Testing: Built-in a11y compliance checks

Test Architecture

• Unit Tests: Component-level testing with React Testing Library
• Integration Tests: End-to-end user flow validation
• API Tests: Next.js route handler testing with custom polyfills
• Snapshot Tests: UI regression prevention
• Mock Strategy: Sophisticated mocking for external dependencies

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• AWS Account with programmatic access
• AWS DynamoDB and S3 access

Installation

1. Clone the repository

   git clone https://github.com/your-username/multi-tenancy-aws.git
   cd multi-tenancy-aws

2. Install dependencies

   npm install

3. Set up environment variables

   Create a .env.local file in the root directory:

   # AWS Configuration
   AWS_ACCESS_KEY_ID=your_access_key_here
   AWS_SECRET_ACCESS_KEY=your_secret_access_key_here
   AWS_REGION=ap-southeast-2
   
   # DynamoDB Table Names
   DYNAMODB_USERS_TABLE=multi-tenancy-users
   DYNAMODB_WORKSPACES_TABLE=multi-tenancy-workspaces
   DYNAMODB_PROJECTS_TABLE=multi-tenancy-projects
   
   # S3 Configuration
   S3_BUCKET_NAME=multi-tenancy-files-bucket

4. Start the development server

   npm run dev

5. Set up AWS resources

   After the server is running, create the required DynamoDB tables and S3 bucket:

   # Create DynamoDB tables
   curl -X POST http://localhost:3000/api/setup-tables
   
   # Create S3 bucket
   curl -X POST http://localhost:3000/api/setup-s3

6. Open your browser

   Navigate to http://localhost:3000 and start using the application!

📖 Usage

Getting Started

1. Register a new account or login with existing credentials
2. Create a workspace for your team or project
3. Add projects within your workspace
4. Upload and manage files for each project

Managing Limits

All system limits can be easily configured in src/config/global-config.ts:

export const LIMITS = {
  WORKSPACES_PER_USER: 10,
  PROJECTS_PER_WORKSPACE: 10,
  FILES_PER_PROJECT: 5,
  MAX_FILE_SIZE_BYTES: 2 * 1024 * 1024, // 2MB
  MAX_FILE_SIZE_MB: 2,
} as const

🏗️ Architecture

Technology Stack

• Frontend: Next.js 15 with React 19 and TypeScript
• Backend: Next.js API Routes
• Database: AWS DynamoDB with Global Secondary Indexes
• File Storage: AWS S3 with hierarchical organization
• UI Framework: Tailwind CSS + shadcn/ui component library
• Components: Radix UI primitives with custom styling
• Authentication: Custom implementation with bcrypt
• Styling: CSS-in-JS with Tailwind utility classes

Data Structure

User
├── Workspaces (max 10)
│   ├── Projects (max 10 per workspace)
│   │   ├── Files (max 5 per project, 2MB each)

AWS Resources

• DynamoDB Tables: Users, Workspaces, Projects
• S3 Bucket: Organized file storage with user isolation
• IAM: Proper permissions for DynamoDB and S3 access

🛠️ Development

Scripts

# Development
npm run dev          # Start development server with Turbopack
npm run build        # Production build
npm run start        # Start production server

# Testing
npm test             # Run all tests
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage

# Code Quality
npm run lint         # Run ESLint

Project Structure

src/
├── app/                 # Next.js App Router
│   ├── api/            # API routes
│   └── globals.css     # Global styles
├── components/         # React components
│   ├── ui/            # shadcn/ui components
│   └── __tests__/     # Component tests
├── config/            # Configuration files
│   └── global-config.ts # System limits and settings
├── contexts/          # React contexts
├── lib/              # Utility libraries
│   ├── auth.ts       # Authentication logic
│   ├── aws-config.ts # AWS SDK configuration
│   ├── project.ts    # Project management
│   ├── storage.ts    # S3 file operations
│   └── workspace.ts  # Workspace management
└── types/            # TypeScript type definitions

Testing

The project includes a comprehensive test suite with 100% test coverage:

• ✅ Unit Tests: Individual component testing (AuthForm, WorkspaceList, FileManager)
• ✅ Integration Tests: End-to-end user flows (auth flow, workspace-project flow)
• ✅ API Tests: Next.js route handler testing (auth, workspaces, projects)
• ✅ Snapshot Tests: UI consistency verification
• ✅ Test Coverage: 61 tests passing across 10 test suites

Test Results:

• 🟢 10 test suites passed (100% success rate)
• 🟢 61 tests passed (all individual tests working)
• 🟢 6 snapshots passed (all snapshot tests working)

Run tests:

npm test                    # All tests
npm test components         # Component tests only
npm test integration        # Integration tests only
npm test api               # API tests only
npm run test:coverage      # Run with coverage report

Test Features:

• Complete Web API polyfills for Next.js API route testing
• Comprehensive mocking strategy for AWS services
• User-centric testing with React Testing Library
• Error scenario coverage for all critical paths
• Accessibility testing included

🔒 Security Features

• Complete User Isolation: All data is scoped to individual users
• Secure File Storage: S3 keys enforce hierarchical access control
• Password Security: bcrypt hashing with high salt rounds
• Pre-signed URLs: Time-limited secure file access
• Input Validation: Server-side validation for all inputs
• Error Handling: Secure error responses without data leakage

🚀 Deployment

Vercel (Recommended)

1. Push your code to GitHub
2. Connect your repository to Vercel
3. Set environment variables in Vercel dashboard
4. Deploy automatically on every push

Manual Deployment

npm run build
npm start

Production Considerations

• Use separate AWS resources for production (-prod suffix)
• Implement proper monitoring and logging
• Set up backup strategies for DynamoDB
• Configure CORS for production domains
• Review and adjust rate limiting

📊 Configuration Options

System Limits

All limits are configurable and enforced both client-side and server-side:

Setting	Default	Description
WORKSPACES_PER_USER	10	Maximum workspaces per user
PROJECTS_PER_WORKSPACE	10	Maximum projects per workspace
FILES_PER_PROJECT	5	Maximum files per project
MAX_FILE_SIZE_MB	2	Maximum file size in MB

UI Configuration

Control which limits are displayed to users:

export const UI_CONFIG = {
  SHOW_LIMITS: {
    WORKSPACE_COUNT: true,
    PROJECT_COUNT: true,
    FILE_COUNT: true,
    FILE_SIZE: true,
  },
} as const

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow the existing code style (ESLint configuration)
• Write tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Documentation

Comprehensive documentation is available in the /docs directory:

• Development Guide - Complete development workflow and best practices
• Testing Guide - Comprehensive testing strategy and implementation
• Testing Achievements - Test suite accomplishments and technical solutions
• Implementation Overview - Technical architecture and features
• Vercel Deployment Guide - Step-by-step deployment instructions

🙋‍♂️ Support

• Documentation: Check the /docs directory for detailed guides
• Issues: Report bugs or request features via GitHub Issues
• Questions: Start a discussion in GitHub Discussions

🔮 Roadmap

• OAuth provider integration (Google, GitHub, etc.)
• File preview functionality
• Real-time collaboration features
• Advanced permission system
• Audit logging and activity tracking
• File versioning support
• Workspace sharing between users
• API documentation with OpenAPI
• Docker containerization
• Kubernetes deployment guides

🎯 Use Cases

Perfect for:

• Development Teams: Separate projects for different clients
• Agencies: Isolated workspaces for each client
• Educational Institutions: Student project management
• Small Businesses: Department-based file organization
• Consultants: Client-specific document management

---

Built with ❤️ using Next.js, AWS, and modern web technologies.

Star ⭐ this repository if you find it helpful!