BuildSphere AI

An AI-powered construction project management platform with live risk analytics, a conversational project assistant, budget and schedule tracking, document intelligence and team collaboration - full-stack, production-ready, and runnable with or without an LLM API key.

Features

• Role-based access control - admin, project_manager, engineer, contractor, client
• Projects - create/edit/archive, progress, budget, risk level, team management
• Kanban tasks - status tracking, priorities, deadlines, assignments, overdue detection
• Budget & expenses - per-category spend, utilization alerts, budget warning/exceeded thresholds
• Milestones & timeline - due dates, completion toggles, overdue flags
• Document intelligence - upload, analyze (PDF/DOCX/XLSX/CSV/images/text), download, AI answers
• AI Risk engine - deterministic score (0-100), factor breakdown, history, re-analysis, critical alerts
• AI Reports - Markdown executive reports generated from live project data
• AI Assistant - conversation history, project-scoped chat, live-data answers
• Dashboard & analytics - KPI cards, budget vs spend, monthly spend, project status donut
• Notifications - deadline/delay/budget/risk/document/milestone events, mark-read, unread badge
• Team management - invite members, roles, titles, companies
• Dark/light theme and a responsive modern UI (shadcn/ui + Tailwind CSS)

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui (Radix), React Query, React Router, Recharts
Backend	Python 3.12+, FastAPI, SQLAlchemy 2, Alembic, Pydantic v2
Database	SQLite (local, zero-config) or PostgreSQL 16 (Docker)
Auth	JWT (HS256) with per-role permissions
AI	OpenAI / Anthropic / OpenAI-compatible + offline deterministic demo provider

Browser
   |
   | /api (reverse-proxied)
+--+---------------------+
| FastAPI  app/          |
|   api/  - routers      |
|   services/ - biz logic|
|   ai/     - llm + risk |
|   models/ schemas/     |
| SQLAlchemy -> SQLite / PostgreSQL |
+--+---------------------+
   |
   v
React SPA (Vite) -> TanStack Query <-> /api

Getting Started

Prerequisites

• Python 3.12+
• Node.js 18+ (npm)
• Docker (optional, for PostgreSQL)

1. Backend

cd backend
python -m venv .venv
.venv\Scripts\activate            # Windows
source .venv/bin/activate         # macOS / Linux
pip install -r requirements.txt

# optional: configure AI (see "AI Providers" below), then run local LLM
uvicorn app.main:app --reload --port 8000

The database auto-creates and seeds demo data on first startup (SQLite by default).

Run tests:

cd backend
.\.venv\Scripts\python -m pytest -q

2. Frontend

cd frontend
npm install
npm run dev

• App: http://localhost:5173 (proxies /api to http://localhost:8000)
• Build: npm run build (type-check + production bundle in dist/)
• Tests: npm test

Demo Credentials (seeded)

Role	Email	Password
Admin	admin@buildsphere.io	admin123
Project Manager	mgr@buildsphere.io	manager123
Project Manager	pm2@buildsphere.io	pm2123
Engineer	eng@buildsphere.io	engineer123
Contractor	contractor@buildsphere.io	contractor123
Client	client@buildsphere.io	client123

Docker

Run the whole stack (PostgreSQL + API + web) with:

cp .env.example .env        # optional
docker compose up --build

• Web app: http://localhost:8080
• API docs: http://localhost:8080/api/docs (or exposed backend port)
• PostgreSQL data and uploaded documents persist in named volumes.

AI Providers

The platform works fully offline with the built-in demo provider (deterministic, clearly labelled) when no API key is configured. To enable real LLM answers:

# OpenAI or any OpenAI-compatible endpoint
AI_PROVIDER=openai
AI_API_KEY=sk-...
AI_MODEL=gpt-4o-mini

# Anthropic
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-...
AI_MODEL=claude-sonnet-4-20250514

Set these in backend/.env (or environment). Demo data and live metrics are always sourced from the database regardless of provider.

API Reference

Interactive docs at http://localhost:8000/docs (OpenAPI). Key routes under /api:

• auth - register, login, me
• users - team CRUD
• projects - CRUD, team members
• projects/{id}/tasks - tasks + /projects/tasks/all
• projects/{id}/budget, .../expenses - budget summary & expenses
• projects/{id}/milestones - milestones
• projects/{id}/documents - upload/analyze/download/delete
• projects/{id}/risk + /risk/analyze - risk overview & re-analysis
• ai - chat, conversations
• reports - report generation
• dashboard, analytics - KPIs and project analytics
• notifications - list, mark-read, read-all

Project Structure

backend/
  app/
    api/        # FastAPI routers
    services/   # business logic (budget, risk, notifications, documents)
    ai/         # LLM provider abstraction, risk engine, report & chat generators
    models/, schemas/, core/, db/
  alembic/      # migrations
  tests/
frontend/
  src/
    services/   # typed API client
    hooks/      # TanStack Query hooks
    components/ # ui (shadcn), common, layout, charts, feature tabs
    pages/      # route pages
    contexts/   # Auth, Theme
    lib/        # http client, utils
docker-compose.yml   # PostgreSQL + backend + frontend (nginx)
.env.example

License

Internal project - see repository owner for details.