DataCenterIQ

Evidence-first project intelligence for data-centre EPC delivery.

Production application · Architecture · Production readiness · Implementation status

DataCenterIQ brings engineering documents, quality workflows, programme risk, supply-chain status, commissioning readiness, RFIs, and project evidence into one secure control environment. It is designed for teams delivering complex data-centre projects where every decision must be traceable to source records.

The platform does not treat generated text as evidence. AI-assisted outputs are bounded by project permissions, grounded in retrieved records, validated by the server, connected to citations, and recorded with confidence and audit metadata.

What the platform covers

• Command center — project identity, delivery health, intervention priorities, connected risks, and transparent productivity calculations.
• Document control — private, resumable ingestion for PDF, scanned PDF, CSV, TXT, JSON, and DOCX files.
• Project Knowledge Copilot — hybrid PostgreSQL full-text and pgvector retrieval, evidence-level citations, deterministic confidence, and evidence-only fallback.
• Compliance and quality — clause-level comparison, QA review, NCR/CAPA workflows, controlled AI-assisted drafting, and immutable evidence links.
• Schedule controls — critical-path calculation, total float, downstream impact, and deterministic blast-radius analysis.
• Supply chain — supplier and shipment tracking, milestone status, delivery exposure, and geospatial context.
• Commissioning — selectable systems, linked readiness evidence, deterministic acceptance evaluation, test-result history, and NCR escalation.
• RFI intelligence — hybrid semantic/lexical decision search, equipment and discipline relevance, controlled prior-decision reuse, and auditable creation.
• Evidence graph — bounded interactive relationship traversal with deep links, record details, and a mobile-readable path view.

The canonical UPS-01 control path demonstrates the complete commissioning decision: the Battery Autonomy Test requires at least 15 minutes, the observed value is 10 minutes, the deterministic result is FAIL, and the result remains connected to its evidence and issued NCR. Gemini does not calculate acceptance outcomes.

Engineering principles

DataCenterIQ is built around a few non-negotiable controls:

1. Supabase PostgreSQL is the authoritative source of truth.
2. Every exposed table is protected by Row-Level Security.
3. Every mutation is authenticated, authorized, validated, and audited server-side.
4. Project documents and generated artefacts remain in private Storage buckets.
5. Gemini and Supabase service-role credentials never enter browser bundles.
6. AI-generated claims must resolve to authorized project evidence before display.
7. Deterministic calculations govern workflow transitions, schedules, readiness, confidence, and productivity.
8. Long-running ingestion work is resumable, idempotent, and explicit about partial or degraded states.

Architecture

DataCenterIQ is a single full-stack Next.js application using the App Router and React Server Components by default.

Browser
  ├─ authenticated Supabase session
  ├─ direct signed uploads to private Storage
  └─ bounded PDF extraction and OCR workers
        │
        ▼
Next.js application
  ├─ Server Components and protected workspace routes
  ├─ independently authorized Route Handlers
  ├─ Zod request and AI-output validation
  ├─ deterministic domain services
  └─ server-only Supabase and Gemini integrations
        │
        ▼
Supabase
  ├─ PostgreSQL with RLS
  ├─ pgvector, PostGIS, pg_trgm, and full-text search
  ├─ private object Storage
  ├─ email/password Auth
  └─ immutable audit and productivity events

The main source boundaries are:

Path	Responsibility
src/app	Routes, layouts, Server Components, and API Route Handlers
src/components	Shared UI, layout, and feedback primitives
src/features	Capability-owned client and presentation code
src/domain	Framework-independent entities, schemas, and constants
src/server	Server-only authorization, persistence, AI, retrieval, and domain services
src/lib	Shared infrastructure and generated Supabase types
supabase/migrations	Forward-only schema, RLS, functions, triggers, and Storage policy changes
tests	Unit, integration, hosted-database, and browser validation

Detailed decisions are recorded in the architecture guide and the ADRs for document ingestion, evidence-first RAG, and NCR/CAPA drafting. The final interface evidence is captured in the frontend audit and visual review.

Technology

• Next.js 16, React 19, strict TypeScript, and Tailwind CSS 4
• Supabase Auth, PostgreSQL, Storage, Row-Level Security, and project-scoped CLI workflows
• PostgreSQL full-text search, pgvector, PostGIS, and Reciprocal Rank Fusion
• Google Gemini generation, multimodal extraction, and 768-dimensional embeddings
• PDF.js, Tesseract.js, Mammoth, and Papa Parse for document extraction
• MapLibre, XYFlow, Recharts, React Hook Form, and Zod
• Vitest, Testing Library, Playwright, ESLint, and Prettier

Access and authorization

The role model is enforced in both server authorization and database policy:

Role	Authority
ADMIN	Organisation settings, projects, membership, roles, and full project access
PROJECT_MANAGER	Project configuration, non-admin membership, schedule, and supply-chain controls
QA_MANAGER	Compliance, NCR/CAPA, and commissioning-quality authority
ENGINEER	Technical project access and permitted execution workflows
CONTRACTOR	Assigned work, uploads, and responses only
AUDITOR	Read-only project access

Database triggers and policies prevent self-escalation, cross-organisation membership changes, cross-project access, unauthorized ADMIN assignment, and removal of the final organisation administrator.

Local development

Prerequisites

• Node.js 20.19 or later
• npm
• A Supabase project
• A Gemini API key for embeddings and AI-assisted workflows

Local Docker is optional. This repository's accepted database validation path uses a linked hosted Supabase project because the original development host had an unavailable Docker runtime.

Setup

git clone https://github.com/nilaysrivastava/datacenteriq.git
cd datacenteriq
npm install
cp .env.example .env.local
npm run dev

Populate .env.local with your own environment values. Never commit it. At minimum, the application expects:

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
GEMINI_API_KEY=
GEMINI_GENERATION_MODEL=gemini-3.5-flash
GEMINI_EMBEDDING_MODEL=gemini-embedding-2
APP_BASE_URL=http://localhost:3000

Only NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are permitted in browser code. All privileged values are loaded exclusively by server-only modules.

Database setup

Link the repository to a Supabase project, apply the forward-only migrations, and generate types from the resulting schema:

npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push
npm run db:types

Regenerate the deterministic seed SQL when its source definitions change:

npm run db:seed

This command writes supabase/seed.sql; it does not apply the file to the linked hosted project. Review generated SQL before running any explicit seed operation, and never reseed a shared or production project destructively.

Development administrator

The guarded bootstrap command creates an administrator only when one does not already exist:

ALLOW_ADMIN_BOOTSTRAP=true npm run bootstrap:admin

Generated credentials are written to .local/admin-login.txt with mode 0600. The directory is ignored by Git, the password is never printed, and repeated runs do not rotate credentials unless explicitly requested. Production execution requires a separate confirmation guard.

Commands

Command	Purpose
npm run dev	Start the local Next.js development server
npm run lint	Run ESLint
npm run typecheck	Run strict TypeScript validation
npm run test	Run the Vitest suite
npm run test:e2e	Run Playwright browser tests
npm run build	Create the production build
npm run check	Run secret scan, lint, typecheck, tests, and build
npm run security:secrets	Scan tracked files, Git history, and browser assets for privileged values
npm run db:test:hosted	Run rollback-protected hosted database tests
npm run db:storage:check	Verify private buckets and tenant-path Storage policies
npm run db:types	Generate TypeScript types from the linked hosted schema
npm run fixtures:documents	Generate deterministic technical document fixtures
npm run reference:complete	Idempotently establish the connected reference workflow
npm run reference:validate	Validate the connected reference workflow
npm run reference:harden	Replace generic seeded labels and isolate assurance-only records
npm run export:source	Create a secret-checked ZIP from the current clean commit

Before merging or deploying, run:

npm run check
npm run test:e2e
npm audit --omit=optional
git diff --check

Finale operational workflow

The Command Center presents a selected, project-scoped intervention as one navigable evidence chain. The reference project traces Clause 7.2.1 through the governed 15-minute-versus-10-minute UPS decision, NCR-274793, deterministic 14-day schedule impact, delayed shipment, 25% current commissioning readiness, RFI-0018, and the bounded Evidence Graph. Selection and linking come from stored relationships; the application does not branch on UPS-specific identifiers.

The reference project stores 30 evidence relationships; each interactive graph traversal is bounded to a maximum of 18 edges for readability.

Knowledge synthesis is evidence-first. Long operations show retrieval, claim-validation, drafting, citation-validation, and persistence stages. If Gemini is unavailable, authorised PostgreSQL retrieval remains usable in evidence-only mode. Controlled out-of-scope, cross-project, absent-evidence, and materially conflicting questions return an explicit refusal instead of a speculative answer.

Manual coordination reduction is reported in hours using stored baseline and measured workflow minutes. No inferred cost-saving claim is produced.

Document and knowledge pipeline

Originals are uploaded directly to private Supabase Storage through short-lived, authenticated signed URLs. The server owns the canonical tenant path and independently verifies the stored object's SHA-256 hash. Native extraction and bounded browser OCR persist page checkpoints immediately, after which server services normalize text, detect clauses, create hierarchical chunks, populate full-text search, and generate validated 768-dimensional embeddings.

Knowledge queries follow this evidence-first path:

authorization → normalized query → metadata filters → lexical + vector retrieval
→ deterministic rank fusion → evidence selection → structured Gemini claims
→ server citation validation → confidence calculation → audit record

If Gemini is unavailable, document ingestion retains full-text indexing and marks semantic work as degraded and retryable. Knowledge queries return the strongest authorized passages in evidence-only mode rather than inventing an answer.

Security and operational posture

• Storage buckets are private and use tenant-scoped canonical paths.
• Signed document URLs are short-lived and issued only after project authorization.
• Extracted content is escaped and treated as untrusted evidence, never as executable instructions.
• Query history, citations, feedback, audit records, and AI drafting evidence remain project-scoped.
• Optimistic versions protect mutable workflow records from lost updates.
• Secret scanning covers tracked files, Git history, generated client assets, and local privileged values without printing them.
• Hosted migrations, schema assertions, RLS tests, Storage-policy tests, vector operations, PostGIS queries, and production browser paths are validated separately.
• Open self-registration is disabled. Organisation administrators issue project access so a new account starts with an authorised project and role; existing-user recovery remains available.
• Project-module access is defined once in src/domain/constants/module-access.ts and shared by navigation, page guards, and privileged action visibility.
• Technical register selections use durable URL parameters (finding, risk, shipment, system, rfi, and entity) for history and direct-link support.
• Quality records follow a human authority chain: deterministic comparison, reviewer disposition, authoritative finding, governed NCR/CAPA drafting, approval, issuance, and linked schedule impact. Gemini never performs arithmetic or grants approval.
• Schedule Risk calculates CPM, float, downstream impact, warning lead time, and mitigation recovery deterministically. Risk records are URL-selectable and link directly to their stored shipment relationship.
• Supply Chain renders each selected shipment's stored PostGIS route through MapLibre and exposes schedule and commissioning impact links. A labelled coordinate view is retained only for map-resource failure.
• Source exports are created under ignored .local/submissions/ from Git-tracked files only, after the secret scan and a clean-worktree check.

See production readiness for current health checks and recovery procedures, and the fragility register for externally dependent risks.

Current status

The production application is deployed at datacenteriq.vercel.app. The hosted schema, private Storage policies, authentication flows, connected EPC workspaces, document ingestion, evidence-first retrieval, and controlled NCR/CAPA drafting have been validated against the linked Supabase environment.

The authoritative capability and verification record is maintained in docs/implementation-status.md. Queue-based OCR scale-out, automated notification delivery, and external supplier feeds remain intentionally outside the current implementation.

Design classifications

• COMPLEX: Tenant isolation, resumable ingestion, deterministic retrieval fusion, claim-level citation validation, connected workflow state, and human approval boundaries add substantial implementation work but produce predictable behavior.
• COMPLEX: CPM forward/backward passes, predictive dates, impact traversal, mitigation scenarios, and PostGIS route resolution keep schedule and logistics decisions reproducible.
• FRAGILE: Hosted Supabase, Gemini quotas and model behavior, browser OCR performance, external map tiles, email delivery, and deployment-network timing depend on external systems. The application exposes degraded states and recovery paths instead of presenting false success.

Repository guidance

Permanent engineering rules live in AGENTS.md. Schema details are documented in docs/data-model.md, and implementation decisions must remain consistent with the forward-only migrations under supabase/migrations.