Orion Portal

Orion is Metiss AI's field service portal. It gives installation teams, dispatchers, and administrators a single place to manage jobs from creation through completion, with AI-generated insights surfaced alongside each job.

What Orion does

When a lead qualifies and a solar installation is confirmed, the work moves into Orion. Field teams use Orion to track every job through its lifecycle — from initial scheduling to on-site execution and invoicing. Administrators manage the user directory, subcontractors, and reports from the same interface.

📋

Job Management

Create, view, edit, and track jobs across active, on-hold, and cancelled states. Filterable tables with search, sorting, and pagination.

🤖

AI Job Insights

Each job surfaces AI-generated insights via the integrated FastAPI service — helping field leads prioritise work and identify patterns.

👥

User & Subcontractor Management

Admin users can manage the team directory, create new users, and manage subcontractor relationships from a dedicated admin section.

🧾

Invoices

View and manage invoices associated with completed jobs. Invoice detail pages show full job and billing context.

📊

Reports

Aggregated reporting across job activity. Active jobs can be exported as CSV for offline analysis.

🔒

Role-based Access

Admin and standard user roles control access to sensitive sections. All routes are protected behind session-based authentication.

Navigation

Route	Purpose
`/jobs/active`	All currently active jobs — the primary working view for field teams.
`/jobs/my-jobs`	Jobs assigned to the logged-in user.
`/jobs/hold`	Jobs paused pending further action.
`/jobs/cancelled`	Cancelled jobs retained for audit history.
`/jobs/create`	Create a new job record.
`/jobs/[id]`	Job detail page including AI insights.
`/invoices`	Invoice list and detail views.
`/reports`	Aggregated job reports and CSV export.
`/users` Admin	User directory — create, view, and edit team members.
`/subcontractor-management` Admin	Manage subcontractor organisations and their access.
`/account`	Personal profile and password management.

Architecture

Orion is a Turborepo monorepo with three runtimes and four shared packages:

Layer	Technology	Role
Frontend	Next.js 16 App Router	Authenticated web shell. All backend calls are proxied through Next.js route handlers — the browser never calls the backend directly.
BFF	EncoreTS	Backend-for-frontend handling auth, jobs, users, invoices, CSV export. Follows strict `api → service → repository` layering.
AI Service	FastAPI (Python)	Serves the `/jobs/insights` endpoint. Called from the BFF, never directly from the browser.
Database	PostgreSQL (Cloud SQL)	Primary data store for users, jobs, sessions, and event logs. Managed with Prisma for schema; runtime queries use the `pg` client directly.
Events	GCP Pub/Sub	Domain mutations publish audit events. Local dev uses an in-process event log; production uses Pub/Sub.

Authentication

Orion uses HTTP-only cookie sessions. On login, the BFF issues a session token stored in a secure cookie. All authenticated routes check the session before rendering. There is no third-party identity provider — credentials are managed within the platform.

Password reset is supported via /forgot-password and /reset-password flows. Tokens are delivered by email and expire after a fixed window.

Deployment

Orion is deployed to GCP Cloud Run with Cloud SQL for PostgreSQL. The CI/CD pipeline uses GitHub Actions with Workload Identity Federation — no long-lived service account keys are stored in GitHub secrets.

Service	GCP resource
Frontend + BFF	Cloud Run (Node.js container, EncoreTS compiled)
AI Service	Cloud Run (Python container)
Database	Cloud SQL for PostgreSQL 16
Audit events	GCP Pub/Sub topic, consumed by `audit-event-consumer-job`

Local development: Run npm run local:start from the repo root to start all three services plus a local PostgreSQL container in one command.