🏗️ SiteOS — Construction Site Operating System

Open-source platform for modern construction management.
Replace WhatsApp groups, Excel sheets, and paper records with one unified system.

SiteOS is a production-grade, open-source Construction Site Operating System built for builders, contractors, civil engineers, and project managers. It digitizes every aspect of construction operations — from project planning and labour tracking to material inventory, equipment management, and financial reporting.

---

✨ Features

📊 Dashboard

Real-time overview of your entire operation — active projects, budget health, labour count, open issues, and alerts.

📋 Project Management

Full project lifecycle: milestones, tasks, issues, progress tracking, budget monitoring, and document management.

👷 Labour & Attendance

Track attendance, overtime, leave, and productivity. Generate payroll-ready exports.

📦 Material Inventory

Manage stock levels, purchase orders, material issues, returns, wastage, and low-stock alerts.

🔧 Equipment Tracking

Monitor equipment usage, maintenance schedules, fuel consumption, and rental availability.

💰 Financial Management

Budget vs actual, expense tracking, invoicing, payment collection, and cash flow analysis.

📓 Daily Site Diary

Record weather, labour counts, work completed, visitors, delays, and progress photos.

📈 Reports & Analytics

Daily/weekly/monthly summaries, budget variance, labour productivity, and material usage — exportable to PDF and Excel.

🔐 Role-Based Access

6 roles: Owner, Project Manager, Site Engineer, Supervisor, Worker, Client (read-only portal).

---

🏛️ Architecture

┌──────────────────────────────────────────────────────┐
│                 React (Next.js 14)                    │
│         TanStack Query · Zustand · Tailwind           │
└──────────────────────┬───────────────────────────────┘
                       │ HTTPS REST
┌──────────────────────▼───────────────────────────────┐
│                 NestJS API (REST)                     │
│         Prisma ORM · JWT Auth · RBAC · Swagger        │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────┴──────────┬──────────┐
│     PostgreSQL      │   Redis  │
│   (Primary DB)      │ (Queue)  │
└─────────────────────┴──────────┘

🚀 Quick Start

Prerequisites

• Node.js ≥ 20.x
• npm ≥ 10.x
• Docker (for PostgreSQL and Redis)

Setup

# 1. Clone and install
git clone https://github.com/JoyalJJoy/siteos.git
cd siteos
cp .env.example .env
npm install

# 2. Start infrastructure
docker compose up -d postgres redis

# 3. Initialize database
npm run db:generate
npm run db:push
npm run db:seed

# 4. Start development
npm run dev

The API runs on http://localhost:4000 and the web app on http://localhost:3000.

Demo Credentials

Role	Email	Password
Company Owner	admin@abc.com	password123
Company Owner	admin@xyz.com	password123

---

🧰 Tech Stack

Frontend

Technology	Purpose
Next.js 14 (App Router)	React framework with SSR/SSG
TypeScript	Type safety
Tailwind CSS	Utility-first styling
Zustand	Client state management
TanStack Query	Server state & caching
Recharts	Charts & visualizations
Lucide React	Icons
framer-motion	Animations

Backend

Technology	Purpose
NestJS	Node.js framework (controllers, services, modules)
TypeScript	Type safety
Prisma	Type-safe ORM with PostgreSQL
PostgreSQL	Primary database
Redis	Queue (BullMQ) & caching
Passport + JWT	Authentication & RBAC
Helmet	Security headers
Pino	Structured logging
Swagger/OpenAPI	API documentation
BullMQ	Background job processing

DevOps

Technology	Purpose
Docker	Containerization
Docker Compose	Local orchestration
GitHub Actions	CI/CD
Husky + lint-staged	Git hooks
Commitlint	Conventional commits

---

📁 Project Structure

siteos/
├── apps/
│   ├── api/                     # NestJS backend
│   │   ├── prisma/              # Schema & migrations
│   │   ├── src/
│   │   │   ├── common/          # Guards, decorators, filters, interceptors
│   │   │   ├── config/          # Environment config
│   │   │   ├── database/        # Prisma service
│   │   │   ├── modules/         # Feature modules (10)
│   │   │   │   ├── auth/
│   │   │   │   ├── users/
│   │   │   │   ├── projects/
│   │   │   │   ├── labour/
│   │   │   │   ├── materials/
│   │   │   │   ├── equipment/
│   │   │   │   ├── finance/
│   │   │   │   ├── daily-diary/
│   │   │   │   ├── dashboard/
│   │   │   │   └── health/
│   │   │   └── main.ts
│   │   └── test/                # E2E tests
│   │
│   └── web/                     # Next.js frontend
│       └── src/
│           ├── app/             # App Router pages (13 routes)
│           ├── components/      # Reusable UI components
│           ├── hooks/           # Custom hooks
│           ├── lib/             # API client, utilities
│           └── store/           # Zustand stores
│
├── .github/                     # Issue/PR templates, CI/CD workflows
├── docker-compose.yml           # Full stack orchestration
└── package.json                 # Workspace root

---

📜 API Documentation

When running in development mode, Swagger UI is available at:

http://localhost:4000/api/docs

All endpoints are versioned under /api/v1/... and require JWT authentication via Bearer token (except /auth/login and /auth/register).

---

🧪 Testing

# Run all tests
npm test

# Backend tests
npm run test:api

# Frontend tests
npm run test:web

# With coverage
npm run test:api -- --coverage
npm run test:web -- -- --coverage

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit using conventional commits
4. Push and open a Pull Request

---

📄 License

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

---

🙏 Acknowledgements

Built with ❤️ by Joyal J Joy and the open-source community.

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: security@siteos.dev

---

_{If SiteOS helps your business, consider ⭐ starring the repo!}