Project Brief: ITECH — MOH-J Lighting Tracker
Client: ITECH Buildings Contracting (Dammam, KSA) Date: 2026-05-31
SCOPE — READ THIS FIRST
This is a full custom build. SMS Group builds everything from scratch: backend AND frontend.
The client used AI to generate HTML reference documents describing the UI and features they want. Those documents are design references ONLY — there is no existing codebase, no existing repo, no existing database. We start from zero.
Do NOT treat this as a backend integration. Do NOT ask for GitHub repo credentials from the client. We create the repo.
What We Are Building
A custom PWA web application hosted on the client's own VPS server. The system manages a lighting installation project across 23 Ministry of Health health centers in Al-Lith and Adham governorates, Saudi Arabia. ITECH is a subcontractor under the Tarshid national energy efficiency program, coordinating 3 field teams across sites up to 290km apart, tracking 9,766 fixtures, and documenting out-of-scope works for contractual claims.
Why the client's own server: All data must stay on the client's infrastructure — no Firebase, no Google, no Supabase, no external cloud services of any kind.
Tech Stack (Fixed — No Alternatives)
- Backend: Python 3.11+ / FastAPI / PostgreSQL
- Frontend: React PWA (Vite) — built by us, mobile-first
- Auth: Custom JWT with bcrypt — no external auth provider
- File Storage: Local filesystem on client's VPS
- Hosting: Client's own VPS (we deploy there)
- PDF export: WeasyPrint (server-side)
- Excel export: openpyxl (server-side)
- Real-time / offline sync: Service Worker + Background Sync API + WebSocket or polling
Features to Build (10 total)
- Project Dashboard — real-time per-site fixture counts, OOS summary, team activity
- Site + Fixture Tracker — 9,766 fixtures across 23 sites, per-fixture status + photo upload
- OOS Works Module — out-of-scope claim submission, dual approval, photo evidence
- Role-Based Access Control — 6 roles, STCE financial blackout enforced at API layer
- Offline Mode + Auto-Sync — full offline capability, auto-sync on reconnect
- Bilingual AR/EN — instant RTL/LTR switch, no page reload
- In-App Notifications — OOS status changes, sync completion, deadline alerts
- Reporting Module — weekly PDF for STCE (no financials), Excel for internal use
- Full Audit Log — every mutation logged, immutable, exportable
- User Training — 6 users, 30 min each, bilingual quick-reference guide
Role Definitions (6 roles)
| Role | Access |
|---|---|
| Operations Director | Full access including financials |
| Project Manager | Full access including financials |
| Team A Engineer | Own team's sites — no financials |
| Team B Engineer | Own team's sites — no financials |
| Team C Engineer | Own team's sites — no financials |
| STCE Representative | View progress + approve OOS only — zero financial visibility, enforced at API level, HTTP 403 on any financial endpoint |
Critical Requirement
STCE financial blackout is non-negotiable. The Main Contractor (STCE) must never see any cost, contract value, or pricing data. This must be enforced server-side in the API response — not filtered in the frontend. A STCE-authenticated request to any financial endpoint must return HTTP 403, not an empty response.
What We Need From the Client (Day 0)
- SSH access to their VPS (IP, username, SSH key or password)
- Domain or subdomain to deploy on
- Logo files (PNG/SVG) for PDF reports
- List of 6 users with names, roles, and email addresses
- Budget deposit confirmed (no work starts without payment)
- Named project contact: name + email + phone, reachable within 2 hours
Timeline
3–4 weeks from Day 1 (after deposit received and server access provided).
Reference Documents (Design Reference Only)
documents/01_Executive_Summary_EN.html— business context, problem statement, user rolesdocuments/02_Full_Project_Plan_EN.html— UI/UX wireframes, user flows, feature descriptions, role definitions
Use these documents to understand what the client wants the system to look like and do. Do not copy their tech stack — they used Firebase/Firestore in the reference docs but we are building with PostgreSQL/FastAPI as specified above.