🏢 My Buildings - Building Management System

A modern, fullstack building management platform built with cutting-edge technologies

Features • Tech Stack • Getting Started • Architecture • Roadmap

👤 Author

Daniel Segura

• GitHub: @daniseguraf
• LinkedIn: linkedin.com/in/daniel-segura-fang

---

🎯 Overview

My Buildings is a fullstack building management application designed to simplify property administration. It includes authentication, authorization, and a modern UI, showcasing end-to-end feature delivery and real-world business logic.

Highlights

• Fullstack TypeScript – React + Node.js with shared types
• Authentication & RBAC – JWT with role-based access
• Scalable Architecture – Monorepo structure and clean separation of concerns
• Modern UI – Responsive interface built with Mantine
• Production Ready – Deployed on Vercel (frontend) and Railway (backend)
• Dockerized DB – Easy local setup and deployment

---

✨ Core Features

• 🔐 Authentication & Authorization

  • JWT authentication and secure session handling
  • Role-based access (Admin, Manager, Resident)
  • Protected routes and API endpoints
  • Login / Logout flows

• 🏢 Building Management

  • Full CRUD operations for buildings
  • Property type classification (Residential, Commercial, Mixed)
  • Detailed infor (floors, address, contact data)
  • Role-based permissions for building operations

• 🏛️ Common Areas

  • CRUD operations for common areas
  • Capacity management and active/inactive status
  • Association with specific buildings
  • Operating hours configuration

• 📅 Reservation System

  • Date and time booking
  • Automatic operating-hours validation
  • Overlap prevention system
  • Maximum duration enforcement
  • Reservation statuses (Confirmed, Cancelled, On Review, Finished)
  • View and manage personal reservations

Next Improvements

• 🎫 Maintenance ticket system
• 📊 Analytics dashboard
• 📧 Email notifications
• 📄 PDF report generation for buildings and reservations
• 🧪 Testing coverage

---

📸 Screenshots

Login Page

Secure authentication with JWT tokens

Buildings List

Manage all your buildings in one place

Building Detail View

Detailed common areas list

Amenities

Building general information

Create new building form

Create new common area form

Reservations Page

Reservations Calendar

My reservations lists

Create reservation form

Manage Reservations

Dark Theme

Buildings page

Building detail page dark theme

---

🛠️ Tech Stack

Backend

• NestJS - Progressive Node.js framework for scalable server-side applications
• Prisma - Next-generation ORM for type-safe database access
• PostgreSQL - Advanced open-source relational database
• pdfmake - Client/server-side PDF printing
• Swagger/OpenAPI - API documentation and type generation
• class-validator - Decorator-based validation

Frontend

• React 19 - Latest React with React Compiler for automatic optimization
• Mantine UI - Comprehensive React component library
• TanStack Query - Powerful data synchronization and caching
• React Router 7 - Modern routing solution
• Zod - TypeScript-first schema validation
• Axios - Promise-based HTTP client
• Vite - Next-generation frontend tooling

DevOps & Tools

• pnpm - Fast, disk space efficient package manager
• Docker - Containerization platform
• TypeScript - Static type checking
• ESLint - Code quality and consistency
• Prettier - Code formatting

---

🏗️ Architecture

Monorepo Structure

my-buildings/
├── packages/
│   ├── backend/                # NestJS API server
│   │   ├── src/
│   │   │   ├── auth/         # Authentication module (JWT, Guards, Strategies)
│   │   │   ├── buildings/    # Buildings CRUD module
│   │   │   ├── common-areas/ # Common areas module
│   │   │   ├── reservations/ # Reservations system
│   │   │   ├── seed/         # Database seeding
│   │   │   ├── printer/      # PDF generation service
│   │   │   ├── prisma/       # Database service
│   │   │   ├── config/       # Environment configuration
│   │   │   ├── common/       # Shared decorators & validators
│   │   │   └── main.ts       # Application entry point
│   │   ├── prisma/
│   │   │   ├── schema.prisma # Database schema
│   │   │   └── migrations/   # Database migrations
│   │   ├── fonts/            # Fonts for PDF generation
│   │   └── test/             # E2E tests
│   │
│   ├── frontend/             # React application
│   │   ├── src/
│   │   │   ├── app/          # App configuration & routes
│   │   │   │   ├── layouts/  # Layout components
│   │   │   │   └── routes/   # Route definitions
│   │   │   ├── features/     # Feature-based modules
│   │   │   │   ├── auth/     # Authentication (Login, Context)
│   │   │   │   ├── buildings/    # Buildings & Common Areas
│   │   │   │   └── reservations/ # Reservation system
│   │   │   ├── components/   # Shared UI components
│   │   │   ├── hooks/        # Custom React hooks
│   │   │   ├── lib/          # Axios & QueryClient configs
│   │   │   ├── utils/        # Helper functions
│   │   │   └── theme.ts      # Mantine theme configuration
│   │   └── public/           # Static assets
│   │
│   └── shared/               # Shared types between FE & BE
│       └── src/
│           └── types/        # Generated TypeScript types
│
├── docs/
│   └── screenshots/          # Application screenshots
├── docker-compose.yaml       # Docker services configuration
└── pnpm-workspace.yaml       # Monorepo workspace config

Design Patterns & Best Practices

• Module-based architecture in NestJS for separation of concerns
• Feature-based structure in React for scalability
• Type generation from OpenAPI specs for type safety across FE/BE
• Repository pattern with Prisma for data access
• DTO validation with class-validator decorators
• Error handling with global exception filters
• API versioning for backward compatibility
• Soft deletes for data integrity

---

🚀 Getting Started

Prerequisites

• Node.js >= 18.x
• pnpm >= 10.23
• Docker & Docker Compose (for database)
• PostgreSQL 14+ (or use Docker)

Installation

1. Clone the repository

git clone https://github.com/daniseguraf/my-buildings.git
cd my-buildings

2. Install dependencies

pnpm install

3. Set up environment variables

Create a .env file in the packages/backend directory:

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/my_buildings?schema=public"
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=my_buildings

# Server
PORT=3000
NODE_ENV=development

4. Start the database

docker-compose up -d

5. Run database migrations

cd packages/backend
pnpm migrate

6. Generate Prisma client and types

cd packages/backend
pnpm generate

Running the Application

Development Mode

Run both frontend and backend concurrently:

# From root directory
pnpm dev

Or run them separately:

# Backend only (http://localhost:3000)
pnpm dev:backend

# Frontend only (http://localhost:5173)
pnpm dev:frontend

Production Build

# Build all packages
pnpm build

# Build individually
pnpm build:backend
pnpm build:frontend

# Start production server
cd packages/backend
pnpm start:prod

---

📡 API Documentation

Once the backend is running, access the interactive API documentation:

• Swagger UI: http://localhost:3000/api/docs
• OpenAPI JSON: Generated automatically in development mode

Key Endpoints

Authentication (/api/v1/auth)

• POST /auth/register - Register new user
• POST /auth/login - Login and get JWT token
• GET /auth/me - Get current user profile
• GET /auth/check-auth-status - Verify authentication status

Buildings (/api/v1/buildings)

• GET /buildings - List all buildings (with filters)
• POST /buildings - Create a new building (Admin/Manager)
• GET /buildings/:id - Get building details
• PATCH /buildings/:id - Update building (Admin/Manager)
• DELETE /buildings/:id - Soft delete building (Admin)
• PATCH /buildings/:id/restore - Restore deleted building (Admin)

Common Areas (/api/v1/common-areas)

• GET /common-areas/building/:buildingId - List areas by building
• POST /common-areas - Create common area (Manager)
• GET /common-areas/:id - Get area details
• PATCH /common-areas/:id - Update common area (Manager)
• DELETE /common-areas/:id - Delete common area (Manager)

Reservations (/api/v1/reservations)

• POST /reservations - Create new reservation (Resident)
• GET /reservations/building - Get reservations by resident's building
• DELETE /reservations/:id - Cancel reservation (Resident/Admin)

Seed (/api/v1/seed)

• GET /seed - Populate database with test data (Development only)

---

📈 Database Schema

The application uses PostgreSQL with Prisma ORM. The schema includes:

Core Entities

• User: Application users with role-based access (Admin, Manager, Resident)

  • Authentication credentials (email, password)
  • Role assignment and building association
  • Relationship with reservations and managed buildings

• Building: Core entity for property management

  • Property information (name, address, type, year built)
  • Soft delete support with deletedAt field
  • Amenities (parking, security, elevator, etc.)

• CommonArea: Shared spaces within buildings

  • Type classification (Gym, Pool, Event Room, etc.)
  • Capacity and availability management
  • Operating hours and days configuration
  • Maximum reservation duration rules

• Reservation: Booking system for common areas

  • Time slot management with overlap prevention
  • Status tracking (In Review, Confirmed, Cancelled, Finished)
  • User and common area associations
  • Attendees count and notes

Key Relationships

User (Manager) ──< manages >── Building
User (Resident) ──< lives in >── Building
Building ──< has >── CommonArea
User ──< makes >── Reservation
CommonArea ──< has >── Reservation

For detailed schema, see packages/backend/prisma/schema.prisma

---

🗺️ Roadmap

See ROADMAP.md for detailed development plan.

Upcoming Features:

---

🎯 What This Project Demonstrates

Backend Skills

• ✅ NestJS with modular architecture and dependency injection
• ✅ Prisma ORM with complex relationships and migrations
• ✅ Complete JWT authentication (Strategy, Guards, Decorators)
• ✅ Complex business validations (no-overlapping reservations)
• ✅ DTOs with class-validator for request validation
• ✅ RESTful API design with proper HTTP methods
• ✅ Proper error handling with custom exceptions
• ✅ Database seeders for test data
• ✅ Soft deletes for data integrity
• ✅ Role-based authorization at endpoint level

Frontend Skills

• ✅ React 19 with TypeScript and strict type checking
• ✅ Context API for global state management
• ✅ TanStack Query for data fetching, caching, and mutations
• ✅ Mantine UI for modern component library
• ✅ Complex forms with real-time validation
• ✅ Protected routes with role-based access control
• ✅ Axios interceptors for authentication
• ✅ Feature-based scalable architecture
• ✅ Custom hooks for reusable logic
• ✅ Loading states, error handling, and empty states

DevOps Skills

• ✅ Monorepo structure with pnpm workspaces
• ✅ Docker Compose for local development
• ✅ Deployment on Railway (backend + PostgreSQL)
• ✅ Deployment on Vercel (frontend)
• ✅ Environment variables per environment
• ✅ Automatic CI/CD with GitHub integration
• ✅ CORS configuration for production
• ✅ Database migrations in production