Parking Management System

Scalable web platform for parking spot allocation with automated raffle-based assignments. Authentication implemented using Supabase Auth (SSR + JWT verification).

---

Project Overview

This system manages parking spot allocation for residential complexes through a transparent, automated raffle process. The architecture demonstrates scalability patterns and production-ready authentication.

Key Features:

• Fair raffle-based parking allocation
• Transparent allocation history tracking
• Role-based access control (admin/resident)
• Automated deployment pipeline
• Foundation for AI integration (LPR)

---

Architecture at a Glance

User → Vercel (Next.js SSR) → Render (Express API) → Supabase (PostgreSQL + Auth)

Tech Stack:

• Frontend: Next.js 15 + React 19 (SSR for performance)
• Backend: Node.js + Express (REST API)
• Database: PostgreSQL via Supabase
• Authentication: Supabase Auth with JWT
• Cache: Custom SSR cache (future: Redis/Upstash)
• Hosting: Vercel (Frontend) + Render (Backend)
• CI/CD: GitHub Actions → Vercel + Render

---

Documentation

This project emphasizes documentation-first development and architectural thinking.

Core Documentation

• Architecture Overview - System design and patterns
• Authentication Guide - Supabase Auth implementation
• Security - Security controls and strategy
• Performance - Optimization and caching
• Frontend Architecture - Frontend patterns and structure

Additional Resources

• Requirements - Functional and non-functional requirements
• Delegation Plan - Team collaboration structure
• Onboarding Guide - Developer setup guide
• Domain Model - Data relationships and business logic

---

Quick Start

Prerequisites

• Node.js ≥ 20
• npm ≥ 9
• Git

Installation

# Clone the repository
git clone https://github.com/manucomi/parking-management-system.git
cd parking-management-system

# Install dependencies
npm install

# Set up environment variables
cp apps/frontend/.env.example apps/frontend/.env.local
cp apps/backend/.env.example apps/backend/.env
# Edit .env files with your credentials

# Initialize database
cd apps/backend
npm run db:init
cd ../..

# Run development servers
npm run dev

Access the Application

Development:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000/api

Production:

• Frontend (Live): https://parking-management-system-frontend-rho.vercel.app/

Preview (PR deployments):

• Automatic preview URL generated for each PR
• Check Vercel bot comment on your PR for the link

For detailed setup instructions, see the Onboarding Guide.

---

🎨 UI/UX Design

All design assets and specifications are organized in /docs/ui/:

• Design References — Complete design documentation
• UI Overview — Component catalog and patterns
• Figma Designs — Original design files (PDF) and exported assets
• SCSS Architecture — Design token implementation

Design → Code Mapping

• Color palette: /apps/frontend/src/scss/variables/_colors.scss
• Typography: /apps/frontend/src/scss/variables/_typography.scss
• Components: /apps/frontend/src/components/

---

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Check coverage
npm run test:coverage

---

🏛️ Project Structure

parking-management-system/
├── apps/
│   ├── frontend/          # Next.js application
│   └── backend/           # Express API server
├── docs/
│   ├── architecture/      # System design & diagrams
│   ├── design-docs/       # ADRs and design decisions
│   ├── requirements/      # Feature specs and requirements
│   ├── team/             # Collaboration and onboarding
│   └── ui/               # Design assets and mockups
├── packages/             # Shared utilities (future)
└── scripts/              # Deployment and automation scripts

---

🤝 Contributing

This project follows a collaborative engineering workflow with automated version management:

1. Create a feature branch from main
2. Make changes with clear commit messages
3. Create a changeset: npm run change:add
   • Documents what changed for release notes
   • Required for all PRs (CI will block without it)
4. Open a PR with description and tests
5. Get reviewed and merge
6. Auto-release - CI automatically:
   • Bumps version (semver)
   • Generates changelog
   • Deploys to production

See Changesets Guide and Delegation Plan for details.

---

Roadmap

MVP (Current - Completed)

• Architecture and design documentation
• Component-based UI structure
• Supabase Auth (SSR with JWT verification)
• Core API endpoints (residents, spots, raffle)
• Database schema implementation
• CI/CD pipeline with automated deployments

Phase 2 — Testing & Hardening

• Backend unit and integration tests
• E2E authentication tests
• Rate limiting and API protection
• Error monitoring and logging

Phase 3 — Additional Features

• Email notifications
• Multi-building support in UI
• Redis caching layer
• Password reset flow

Phase 4 — AI Integration

• License Plate Recognition API
• Real-time parking status
• Analytics dashboard

---

Security & Performance

• Authentication: Supabase Auth with JWT-based API protection
• Authorization: Role-based access control (admin/resident)
• Data Protection: HTTPS, HTTP-only cookies, input validation
• Performance: SSR caching, database indexing, connection pooling
• Scalability: Horizontal scaling ready, cloud-agnostic design

See detailed documentation:

• Security Strategy
• Performance Guide

---

Project Status

• Authentication implemented
• Backend tests pending
• Ready for production hardening