GP Data Platform + SFMS — Engineering Build Plan
Product: Atlas Data Platform + Smart Facility Management System (SFMS) Codename: Tsugumi (placeholder) Reference inspiration: ThingsBoard (open-source IoT platform) + ISO 41001 Smart FM Status: v1.0 — engineering plan handed to the team Owner: Engineering Lead (to be named) Issued: Planning document for execution
This folder contains the full Software Development Lifecycle (SDLC) plan for the GP Atlas Data Platform and Smart Facility Management System (SFMS). The plan is decomposed into 10 phases that an engineering team can pick up and execute in order. Some phases parallelize after Phase 2 (see §Sequencing below).
1. Product summary
A multi-tenant Data Platform + SFMS that ingests building telemetry and operational data (BMS, IoT, work orders, asset ledger, documents) into a governed canonical schema, exposes it through:
- Customisable drag-and-drop dashboards (per-user, theme-aware, with TV-wall and war-room modes)
- Modular widget library drawn from every module (asset, work order, telemetry, AI, workflow)
- OpenAPI 3.x developer API with Swagger UI / Scalar for third-party integration
- AI Second Brain that auto-categorises data, suggests workflows, and answers natural-language questions over the platform
- Visual Workflow Creator Studio (drag-and-drop nodes, approval flows, triggers, conditions, AI steps)
- Mobile-first PWA with responsive views, offline inspection mode, and push notifications
Everything is built full-stack Next.js 15+ (App Router) with MongoDB as the primary data store (URI configured via .env). UI is modern, themable (light/dark + brand themes), and component-driven.
2. Phase inventory
| # | Phase | Purpose | Duration | Gate |
|---|---|---|---|---|
| 0 | Foundation & Setup | Repo, CI/CD, environments, tooling, design system | 1 week | G0 |
| 1 | Requirements & Architecture | Full FRS + NFRS, system architecture, data model, ADRs | 2 weeks | G1 |
| 2 | Core Platform | Next.js scaffold, MongoDB, Auth/RBAC, OpenAPI/Swagger, audit | 3 weeks | G2 |
| 3 | Data Platform | Ingestion, ontology, connectors (BACnet/MQTT/REST), time-series | 4 weeks | G3 |
| 4 | SFMS Core Modules | Asset, Location, System, Work Order, Document, Notifications | 4 weeks | G4 |
| 5 | Dashboard System | Widget framework, drag-drop layout, themes, TV / war-room modes | 4 weeks | G5 |
| 6 | AI Second Brain | LLM integration, auto-categorisation, NL query, RAG, agent loops | 4 weeks | G6 |
| 7 | Workflow Creator Studio | Visual designer, state machine, approvals, triggers, audit | 3 weeks | G7 |
| 8 | Mobile + PWA | Responsive, PWA, offline mode, push notifications, mobile UX | 2 weeks | G8 |
| 9 | QA, Security, Deploy | Test, pentest, performance, hardening, deploy, handover | 2 weeks | G9 |
Total elapsed: ~29 weeks single-thread, ~22 weeks with Phase 4–8 partially parallelised.
3. Sequencing
P0 ─┐
├─▶ P1 ──▶ P2 ──┬──▶ P3 ──┬──▶ P4 ──▶ P9
│ ├──▶ P5 ──▶ P9
│ ├──▶ P6 ──▶ P9
│ └──▶ P7 ──▶ P9
└─────────────▶ P8 ──▶ P9
- P0–P2 are strictly sequential (foundation → architecture → core platform).
- P3 must complete before P4 (SFMS modules read from the data platform).
- P5 (Dashboards), P6 (AI), P7 (Workflow), P8 (Mobile) can run in parallel after P4 ships, sharing the platform foundation.
- P9 (QA / Deploy) integrates everything before go-live.
4. Engineering principles
- Spec-driven — every endpoint is in the OpenAPI spec before code is written. Generated types power both server and client.
- Schema-first — every collection is defined with Zod/Joi schemas and Mongoose models (or native MongoDB validators) before any business logic.
- Multi-tenant from day one — every collection is tenant-scoped; tenant isolation is enforced at the data layer, not just the application layer.
- RBAC + ABAC — role-based defaults with attribute-based overrides for fine-grained per-record access.
- Audit by default — every mutating action writes to an immutable audit log; AI decisions include reasoning trace.
- Real-time first — WebSocket / SSE channels for live data; REST for CRUD.
- Componentized — Tailwind + shadcn/ui as base, with a documented design system in Storybook.
- Test pyramid — unit (Vitest/Jest), integration (Playwright API), end-to-end (Playwright UI), with ≥80% coverage on business logic.
- Observability by default — OpenTelemetry traces, Prometheus metrics, structured logs; SLOs defined per service.
- Documentation as code — every PR updates relevant ADRs, OpenAPI spec, runbook, and changelog.
5. Technology stack (final)
| Layer | Choice | Notes |
|---|---|---|
| Runtime | Node.js LTS (≥20) | Next.js 15+ requirement |
| Framework | Next.js 15+ (App Router) | Full-stack: UI + API Route Handlers + Server Actions |
| Language | TypeScript (strict) | No JS in product code |
| Database | MongoDB 7+ | URI in .env (MONGODB_URI); Atlas in prod |
| ODM | Mongoose 8+ | Or native driver behind a repository layer |
| Time-series | MongoDB Time Series Collections | For BMS / IoT telemetry |
| Vector | MongoDB Atlas Vector Search | For RAG / Second Brain |
| Auth | Auth.js (NextAuth v5) | OIDC, SAML via providers, MFA |
| Styling | Tailwind CSS + shadcn/ui | Theming via CSS variables |
| State | TanStack Query + Zustand | Server state + client state |
| Forms | React Hook Form + Zod | Schema-shared client/server |
| Charts | Recharts + ECharts | Recharts for simple; ECharts for advanced |
| Dashboard grid | react-grid-layout | Drag-drop layout |
| Workflow canvas | React Flow | Visual workflow designer |
| API docs | Swagger UI + Scalar | Mounted at /api/docs |
| OpenAPI spec | next-swagger-doc or zod-to-openapi | Source of truth |
| Realtime | Server-Sent Events (default) + WebSocket where needed | Via Next.js route handlers |
| Queue | BullMQ + Redis | For background jobs |
| AI | Provider-agnostic SDK (OpenAI, Anthropic, Ollama) | Configured via .env |
| Object store | S3-compatible (MinIO local, AWS S3 prod) | For documents, exports |
| Observability | OpenTelemetry + Grafana stack | Logs/metrics/traces |
| CI/CD | GitHub Actions | Lint, test, build, scan, deploy |
| Container | Docker + Kubernetes (optional) | Single-binary Next.js viable for SMB |
| Mobile | PWA (no native shell required initially) | Add Capacitor later if needed |
6. Phase document conventions
Each Phase_N.md follows the same structure for predictability:
- Header (status, owner, duration, gate)
- Overview — what this phase is and why
- Objectives — measurable outcomes
- Scope — in / out of scope
- Dependencies — prior phases or external
- Architecture & Design — diagrams (in ascii / mermaid), key decisions
- Detailed Specifications — module by module
- Implementation Tasks — broken into Epics / Stories
- Acceptance Criteria — testable
- Test Requirements — what types of tests, coverage targets
- Documentation Requirements — what gets written / updated
- Sign-off Criteria — gate conditions
- Risks & Mitigations
Stories are written in user-story format: "As a [role], I want [capability], so that [value]."
7. Gates and sign-offs
Each phase ends with a gate (G0–G9). A gate is passed only when:
- All acceptance criteria for the phase are met
- All required documents in the phase are produced and reviewed
- All Sev-1 and Sev-2 defects are closed
- The phase demo is accepted by the Product Owner and Engineering Lead
Gate sign-off is recorded in _gates/Gate_GN_signoff.md (template provided in Phase 0).
8. File index
00_README.md— this fileMASTER_PLAN.md— consolidated roadmap: timeline, critical path, RACI, gate calendar, cross-cutting workstreams../design/— UX & design specification (personas, journeys, IA, design system, patterns, wireframes); a gate input to P1/P2/P4/P5/P8Phase_0.md— Foundation & SetupPhase_1.md— Requirements & ArchitecturePhase_2.md— Core PlatformPhase_3.md— Data PlatformPhase_4.md— SFMS Core ModulesPhase_5.md— Dashboard SystemPhase_6.md— AI Second BrainPhase_7.md— Workflow Creator StudioPhase_8.md— Mobile + PWAPhase_9.md— QA, Security, Deployment
9. How to use this plan
For the Engineering Lead: read 00_README.md (this file) and Phase_1.md end-to-end before starting Phase 0. Confirm scope with the Product Owner. Assign owners for each phase.
For an Engineer picking up a phase: read Phase_(N-1).md first to understand inputs, then your phase. Each story is independently scoped; you can branch and PR per story.
For the QA Lead: test requirements at the bottom of each phase are non-optional. Build the test plan from these.
For the Product Owner: review the Acceptance Criteria sections — these are the demos the team will run for sign-off.