This project has been created as part of the 42 curriculum by abadouab, amabrouk, bikourar and eghalime.
A self-hosted code collaboration platform built from the ground up as a microservice architecture. CodeLab provides Git repository hosting with a web interface for browsing files, viewing commit history, managing branches, and tracking issues — similar in spirit to GitHub or GitLab but designed, built, and deployed entirely by our team.
CodeLab is a full-stack web application where users can create and manage Git repositories through a modern browser-based interface. The platform supports user authentication (local credentials and OAuth via Google and GitHub), repository creation and deletion, file browsing across branches and commits, and collaborative repository management with role-based access control.
The backend is split into two independent services: an API Gateway that handles authentication, user management, and request orchestration, and a Git Engine that wraps native Git operations into a REST API. Both services communicate over Docker's internal network, with Nginx sitting in front as a reverse proxy handling SSL termination and routing.
- User registration and login with email/password
- OAuth 2.0 authentication via Google and GitHub
- Git repository creation and management
- File and directory browsing across branches and commits
- Commit history viewing
- Branch creation and management
- Role-based repository access (Read, Write, Admin)
- Personal Access Tokens for Git HTTPS operations
- Interactive API documentation via Scalar
- Responsive frontend with a custom design system
- Docker (version 20.10 or higher) —
docker --version - Docker Compose (version 2.0 or higher) —
docker compose version - Make —
make --version
make setupThis generates SSL certificates, creates the .env file, builds all Docker images, starts the services, and initializes the database.
After setup, edit transcendence/.env with your secrets. Generate them with:
# JWT secret (minimum 32 characters)
openssl rand -hex 32
# Database password
openssl rand -base64 24Required variables:
DB_USER=codelab
DB_PASSWORD=<generated-password>
DB_NAME=codelab
DB_PORT=5432
JWT_SECRET=<generated-jwt-secret>
NODE_ENV=development
VITE_API_URL=https://localhost/api
NGINX_HTTP_PORT=80
NGINX_HTTPS_PORT=443
GIT_PORT=4000
REPO_ROOT=/repositories
GIT_ENGINE_URL=http://git-engine:4000
GITHUB_ID=<your-github-oauth-app-id>
GITHUB_SECRET=<your-github-oauth-app-secret>
GOOGLE_ID=<your-google-oauth-client-id>
GOOGLE_SECRET=<your-google-oauth-client-secret>A .env.example file is provided as a reference template.
make up # Start in foreground (see logs)
make up-d # Start in background
make down # Stop all services
make restart # Restart all services
make rebuild # Rebuild and restart| Service | URL |
|---|---|
| Frontend (via Nginx) | https://localhost |
| API Gateway (via Nginx) | https://localhost/api |
| Git Engine (via Nginx) | https://localhost/git |
| API Documentation | http://localhost:3000/docs |
| Prisma Studio | http://localhost:5555 |
| Database | localhost:5432 |
make help # Show all available commands
make status # Check container status
make health # Check service health
make logs # View logs from all services
make db-studio # Open database GUI
make shell-frontend # Shell into frontend container
make shell-api # Shell into api-gateway container
make shell-git # Shell into git-engine container
make clean # Stop and remove containers, networks, volumesFor detailed development workflows (installing dependencies, database migrations, troubleshooting), see the Development Setup Guide.
- Framework: React 19
- Language: TypeScript
- Build Tool: Vite
- Styling: Tailwind CSS v4
- Routing: React Router DOM
- HTTP Client: Axios
React with TypeScript provides type safety and component reusability for building a complex collaborative interface. Vite offers fast HMR for a smooth development experience. Tailwind CSS allows rapid construction of a custom design system with utility classes.
- Framework: Express
- Language: TypeScript
- API Architecture: RESTful with microservice communication
- Authentication: JWT (httpOnly cookies) + Passport.js (OAuth 2.0)
- Validation: Zod
- Logging: Winston
- API Documentation: Scalar (OpenAPI 3.1.0)
Express is lightweight and flexible with strong TypeScript support. JWT via httpOnly cookies provides secure stateless authentication. Passport handles the OAuth flows for Google and GitHub. TypeScript across both frontend and backend ensures type consistency.
- System: PostgreSQL (Alpine)
- ORM: Prisma 7
PostgreSQL provides robust relational data management with ACID compliance for concurrent operations. Prisma gives us type-safe database queries, automatic migrations, and schema management that integrates naturally with our TypeScript stack.
- Containerization: Docker
- Orchestration: Docker Compose
- Reverse Proxy: Nginx with SSL/TLS termination
- Protocol: HTTPS everywhere (self-signed certificates for development)
┌─────────────────────────────────────────────────────────────┐
│ Nginx (443) │
│ (Reverse Proxy + SSL) │
└───────┬──────────────────┬──────────────────┬───────────────┘
│ │ │
│ / │ /api/* │ /git/*
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌──────────────┐
│ Frontend │ │ API Gateway │ │ Git Engine │
│ (React) │ │ (Express) │ │ (Express) │
│ Port 5173 │ │ Port 3000 │ │ Port 4000 │
└───────────────┘ └───────┬───────┘ └──────────────┘
│
│ Prisma ORM
│
▼
┌───────────────┐
│ PostgreSQL │
│ Port 5432 │
└───────────────┘
All client requests pass through Nginx. The API Gateway authenticates requests, resolves human-readable identifiers (username/repo-name) to UUIDs, and forwards Git operations to the Git Engine over Docker's internal network.
┌──────────────────────┐ ┌──────────────────────────┐
│ User │ │ Repository │
├──────────────────────┤ ├──────────────────────────┤
│ id (uuid pk) │──┐ │ id (uuid pk) │
│ email (unique) │ │ │ name │
│ username (unique) │ │ │ description │
│ password (optional)│ │ │ isPrivate (bool) │
│ fullName │ │ │ defaultBranch ("main") │
│ bio │ ├───▶│ ownerId (fk→User) │
│ avatarUrl │ │ │ createdAt / updatedAt │
│ provider ("local") │ │ └──────┬───────────────────┘
│ providerId │ │ │
│ createdAt / updatedAt│ │ │ unique(ownerId, name)
└──────────┬───────────┘ │ │
│ │ │
│ │ ┌──────┴───────────────────┐
│ │ │ Collaborator │
│ │ ├──────────────────────────┤
│ │ │ id (uuid pk) │
│ └───▶│ userId (fk→User) │
│ │ repoId (fk→Repository) │
│ │ role (READ/WRITE/ADMIN)│
│ │ unique(userId, repoId) │
│ └──────────────────────────┘
│
│ ┌──────────────────────────┐
│ │ PersonalAccessToken │
│ ├──────────────────────────┤
│ │ id (uuid pk) │
└────────▶│ userId (fk→User) │
│ name │
│ tokenHash (unique) │
│ lastUsedAt / expiresAt │
│ createdAt │
└──────────────────────────┘
Relationships: A User owns many Repositories. A Repository has many Collaborators (join table with role). A User can have many PersonalAccessTokens for Git HTTPS auth.
| Feature | Description | Team Member(s) |
|---|---|---|
| Docker infrastructure | Complete Docker Compose setup with 5 services, Makefile automation, health checks, setup scripts | eghalime |
| Nginx reverse proxy | HTTPS/SSL termination, routing to frontend/api/git services, HTTP→HTTPS redirect | eghalime |
| Git Engine service | SOA-based microservice with full Git workflow: commits, branches, diffs, trees, blobs, Smart HTTP protocol | abadouab |
| API Gateway core | Request routing, RPC integration with Git Engine, repository CRUD with transactional rollback | abadouab |
| API documentation | OpenAPI 3.1.0 spec with Scalar interactive docs covering 35 endpoints | abadouab |
| Error handling | Global error handler with Prisma error mapping, AppError utility, catchAsync wrapper, Winston logging | abadouab, eghalime |
| Prisma schema & DB | PostgreSQL schema with 4 models, relations, role-based access, migration setup | abadouab |
| Authentication backend | Local registration/login with bcrypt, JWT httpOnly cookies, Passport strategies for Google and GitHub, Zod validation | bikourar |
| Authentication frontend | AuthContext with login/register/logout, cookie-based auth flow, protected/public route guards | eghalime |
| Auth UI | Sign-in/register page with form validation, error handling, OAuth buttons, loading states | eghalime |
| Frontend routing | React Router setup with protected routes, param-driven repo pages, auth redirects | eghalime |
| API layer | Axios instances for API Gateway and Git Engine with credentials, request/response typing | eghalime |
| Repository page | File browsing, branch switching, commit info, visibility badges, tab navigation | eghalime |
| UI component library | Reusable design system: Avatar, Button, Checkbox, Input, Tabs, FileTree, ProfileCard, InfoRow, StatButton, IconBox, PageHeader, SidebarCard, FormField, InfoAlert | amabrouk |
| Frontend redesign | Full theme migration, page redesign for consistency, layout components | amabrouk |
| Settings page | User settings with profile editing, account deletion modal, navigation sections | amabrouk |
| Terms & Privacy pages | Legal compliance pages accessible from the footer | eghalime |
| Tailwind design system | Tailwind CSS v4 setup, color palette from Figma, typography scale | eghalime |
| # | Module | Category | Type | Points | Implementation |
|---|---|---|---|---|---|
| 1 | Use a framework for both frontend and backend | Web | Major | 2 | React (frontend) + Express (backend) |
| 2 | Use an ORM for the database | Web | Minor | 1 | Prisma 7 with PostgreSQL |
| 3 | OAuth 2.0 remote authentication | User Management | Minor | 1 | Google and GitHub via Passport.js |
| 4 | Backend as microservices | DevOps | Major | 2 | API Gateway, Git Engine, and Frontend as independent Docker services with REST communication |
| 5 | Custom-made design system | Web | Minor | 1 | 14+ reusable components with consistent color palette, typography, and iconography |
Confirmed total: XX points
| Name | Login | Role(s) | Responsibilities |
|---|---|---|---|
| Abou Qatada Adouab | abadouab | Product Owner, Technical Lead, Developer | Defines product vision and priorities, makes architecture decisions, oversees code quality, implements Git Engine and API Gateway core |
| Adil Mabrouk | amabrouk | Developer | Implements UI component library, frontend redesign, and page layouts |
| Bilal Kourar | bikourar | Developer | Implements backend authentication system, OAuth integration, and security hardening |
| El Mehdi Ghalime | eghalime | Scrum Master, Developer | Facilitates team coordination, tracks progress, manages risks, implements Docker infrastructure, frontend auth flow, and routing |
- Task Distribution: Work is divided by service domain — each member owns specific layers of the stack. Features are tracked through GitHub Issues with labels for module, priority, and service area.
- Meeting Schedule: Regular syncs to review progress, plan sprints, and resolve blockers.
- Decision Making: Architecture and technology decisions are proposed by the Technical Lead and discussed as a team. The Product Owner has final say on feature priorities.
- Version Control: Git & GitHub with feature branch workflow
- Communication: Discord for daily communication and quick questions
- Task Tracking: GitHub Issues with labels (feature, bug, module, priority levels)
- Code Review: Pull Request process requiring at least one approval before merge
Roles: Product Owner, Technical Lead, Developer
Contributions:
- Designed and implemented the Git Engine microservice with full Git workflow support (commits, branches, diffs, trees, blobs) and Smart HTTP protocol
- Built the API Gateway core with repository CRUD, RPC integration to Git Engine, and transactional rollback on failure
- Created the OpenAPI 3.1.0 specification with Scalar interactive documentation
- Designed the Prisma database schema (4 models with relations and role-based access)
- Implemented global error handling with Prisma error mapping and Winston logging
- Migrated the project to Prisma 7 with improved type safety and configuration
- Managed the product backlog and validated completed features
Challenges & Solutions: Bridging the API Gateway and Git Engine required a reliable RPC layer that could handle transactional operations — if the database record was created but the bare Git repository failed to initialize, the system needed to roll back cleanly. This was solved with explicit rollback logic in the repository creation flow.
Roles: Developer
Contributions:
- Built a comprehensive UI component library with 14+ reusable components (Avatar, Button, Checkbox, Input, Tabs, FileTree, ProfileCard, InfoRow, StatButton, IconBox, PageHeader, SidebarCard, FormField, InfoAlert)
- Redesigned all frontend pages for visual consistency across the application
- Implemented the Settings page with profile editing and account deletion
- Migrated the frontend to a unified theme color palette
- Created layout components (Footer, page structures) used across the application
Challenges & Solutions: Establishing a consistent design language across a growing number of pages required building a centralized component library early. Components were designed to be composable and theme-aware, allowing page-level redesigns without rewriting individual elements.
Roles: Developer
Contributions:
- Implemented the full backend authentication system with local registration and login using bcrypt password hashing
- Built JWT-based session management with secure httpOnly cookies
- Integrated Passport.js strategies for Google and GitHub OAuth 2.0
- Added Zod-powered environment and payload validation for all auth endpoints
- Updated the Prisma User model to support both local and OAuth accounts (optional password, provider/providerId fields)
- Hardened security with strict CORS configuration, safe cookie flags, and improved secrets handling
Challenges & Solutions:
Supporting both local and OAuth authentication required a flexible user model — OAuth users don't have passwords, while local users don't have provider IDs. This was solved with optional fields and a unified handleOAuthLogin method that creates or links accounts based on email or provider ID matching.
Roles: Scrum Master, Developer
Contributions:
- Designed and built the complete Docker infrastructure: Docker Compose with 5 services, Makefile with 30+ commands, setup and health check scripts
- Configured Nginx as a reverse proxy with HTTPS/SSL termination, routing rules for frontend/api/git, and security headers
- Implemented the frontend authentication flow: AuthContext with login/register/logout, cookie-based session management, ProtectedRoute and PublicRoute guards
- Built the AuthPage with form validation, error handling, OAuth buttons, and loading states
- Created the API layer with Axios instances for both the API Gateway and Git Engine
- Implemented the RepoPage with file browsing, branch switching, and commit information
- Set up Tailwind CSS v4 with the design system color palette and typography
- Created the Terms of Service and Privacy Policy pages
- Connected the frontend auth UI to the backend API with proper cookie/CORS configuration
- Wrote project documentation (README, DEVELOPMENT_SETUP.md)
- Facilitated team coordination, tracked progress, and managed blockers
Challenges & Solutions:
Getting authentication to work end-to-end across the full stack (frontend → Nginx → API Gateway) required coordinating several layers: the frontend needed withCredentials: true on Axios, Nginx needed to pass cookies through the proxy, the API Gateway needed cookie-parser middleware and CORS with credentials: true, and cookies needed correct sameSite and secure flags. Each layer had to be configured consistently for the httpOnly JWT cookie to survive the round trip.
- React Documentation
- Express.js Guide
- Prisma Documentation
- Passport.js Documentation
- Docker Compose Documentation
- Nginx Reverse Proxy Guide
- Tailwind CSS v4 Documentation
- Vite Documentation
- OpenAPI 3.1.0 Specification
AI tools were used during development for generating boilerplate code, particularly for scaffolding reusable frontend components and repetitive configuration structures. All AI-generated code was reviewed, tested, and adapted by team members before integration. Core architecture decisions, business logic, authentication flows, and Git operations were designed and implemented by the team.
- Development Setup Guide — Complete setup, daily workflow, database management, and troubleshooting
- Create a feature branch:
git checkout -b feature/your-feature-name - Make your changes following our coding standards
- Commit with clear messages:
git commit -m "Add: feature description" - Push to your branch:
git push origin feature/your-feature-name - Create a Pull Request with a clear description
- Wait for code review from at least one team member
- Merge after approval (use squash merge for cleaner history)
Add:new featuresFix:bug fixesUpdate:updates to existing featuresRefactor:code refactoringDocs:documentation changesStyle:formatting changesTest:adding tests