Xiber NetOS — Roadmap & Known Gaps
What's built, what's missing, and the recommended path forward.
Current Phase: Foundation Prototype
The current build delivers a working UI and API for circuit lifecycle visibility. Core CRUD, bulk edit/delete, mapping, dashboards, import, audit activity, and the admin feedback queue are functional. Authentication hardening, financial accuracy, renewal automation, and document ingestion remain the primary gaps before production use.
Feature Inventory
What's Built
| Area | Details |
|---|---|
| Monorepo scaffold | apps/api, apps/web, apps/mcp, packages/shared, infra/docker |
| Database schema | 13+ tables, PostGIS geometry, pgvector embeddings, materialized financial view |
| Migrations | Alembic baseline + infrastructure + agreements migrations |
| API | FastAPI with OpenAPI 3.1, circuit CRUD, bulk actions, map, dashboard, import, providers, infrastructure |
| Circuit table | Search, filter by carrier/status/type, bulk edit/delete, click-through to detail |
| Circuit detail | Full attributes, endpoints, carrier info, NOC contacts, contract terms, lifecycle history |
| Map | A→Z circuit lines, endpoint dots, infrastructure markers, colored by provider, thickness by bandwidth |
| Dashboard | 17 KPI cards/panels including spend by carrier, service mix, renewal pipeline, at-risk circuits |
| Timeline | Contract-term Gantt with install markers, renewal deadlines, today line, state colors |
| Topology | Endpoint graph with logical/geographic layouts, SPOF detection, carrier-colored edges |
| Service providers | Portal links, NOC phones, account managers, circuit/infra counts, ETF exposure |
| Infrastructure | Data centers, towers, colos, rooftops, carrier hotels, POPs, offices, and aggregation facilities with costs, terms, and bulk edit/delete |
| Electrical | Utility service accounts attached to infrastructure or customer sites, with provider, meter, service details, average monthly cost, monitoring link, and documents |
| Financial / P&L | Per-circuit modeled revenue, margin, ETF exposure, carrier spend rollups, and infrastructure attribution foundation |
| Address lookup | Search circuits by address, endpoint, city, state, carrier, or circuit ID |
| Mobile field view | Phone-friendly circuit lookup with NOC call, copy ID, and map links |
| Admin / audit | Recent activity trail plus bug/feature queue with priority, status, and progress comments |
| CSV/XLSX import | Heuristic column mapping, staging, upsert by natural key, auto-stub carriers/endpoints |
| Sample data | 4 carriers, 10 endpoints, 8 circuits with contracts and lifecycle events |
| MCP tools | Token-aware read/context tools for search, circuits, infrastructure, customers, RF links, quotes, carrier summary, renewal pipeline, and site documents/photos |
| RBAC | 8 roles defined, dev shim accepts x-user-role header |
| Docker dev stack | PostgreSQL 16, Redis 7, API, Web with hot reload |
Gap Analysis
1. Authentication & Authorization
| Detail | |
|---|---|
| - | -------- |
| Current | Header-based dev shim (x-user-role: exec) plus support for common SSO email headers when present. Direct/demo mode falls back to dev@xiber.com. |
| Impact | Cannot deploy to production. No audit trail of who did what. |
| Needed | Microsoft Entra OIDC JWT validation on API. Role assignment from Entra groups/claims. Session handling in Next.js (cookie-based, server-side). Token refresh flow. |
| Depends on | Entra app registration (see Public Hostname & SSO) |
2. Audit Logging
| Detail | |
|---|---|
| - | -------- |
| Current | Activity logging exists for request/write activity, feedback, and bulk actions. created_by/updated_by are populated on newer write paths. |
| Impact | Basic accountability exists, but sensitive read tracking and field-level redaction are incomplete. |
| Needed | Complete field-level before/after coverage for all write paths. Field-level read audit for sensitive data (ETF formulas, banking, MD5 keys). Sensitive field redaction on read by role. |
3. CSV/XLSX Import Enhancements
| Detail | |
|---|---|
| - | -------- |
| Current | Heuristic column mapping. Staging rows. Commit valid rows. Upsert by natural key. |
| Impact | Column mapping is fragile for non-standard headers. No way to fix staging errors in-app. |
| Needed | Claude Opus 4.7 mapping (send headers + 5 sample rows, get canonical mapping). Saved mappings by (user, source_signature). Inline staging row editor. Diff preview before updating existing circuits. Explicit confirmation dialog before overwriting financial fields. |
4. PDF Contract Ingestion
| Detail | |
|---|---|
| - | -------- |
| Current | Contract and AgreementExtraction schemas exist. No upload or extraction pipeline. |
| Impact | Contract data must be entered manually or via CSV. |
| Needed | PDF upload endpoint with S3/MinIO object storage. pdfplumber text extraction with pytesseract OCR fallback. Claude Opus 4.7 structured extraction (carrier, term, MRC, ETF formula, renewal terms). Confidence scoring with source quotes and page numbers. Side-by-side approval UI (PDF viewer left, extracted fields right). Mandatory human approval for MRC, ETF, and term fields before commit. |
5. Renewal Engine
| Detail | |
|---|---|
| - | -------- |
| Current | Renewal states computed on-the-fly in API/frontend. No persistent tracking or notifications. |
| Impact | No proactive alerts. Renewal deadlines can be missed. |
| Needed | Nightly Celery job to compute and persist renewal states (stable → watch → active → critical → overdue → decided). Materialized view or state table refresh. Email, Slack, and Monday.com notifications on state transitions. Decision workflow UI (renew / negotiate / terminate / port). DocuSeal termination notice generation. Test-mode fast-forward for QA. |
| State machine | stable (>180d) → watch (90–180d) → active (30–90d) → critical (<30d) → overdue (past deadline) → decided |
6. Dashboard & Financial Accuracy
| Detail | |
|---|---|
| - | -------- |
| Current | Circuit-level modeled MRR uses MRC * 1.35 placeholder multiplier. Infrastructure detail now has subtended links, direct/downstream revenue and cost rollups, relationship effective dates, and circuit-linked attribution records. |
| Impact | Circuit margin remains illustrative until Sonar revenue is connected. Infrastructure economics can be modeled manually now, but allocation methods, period reporting, and actual invoice/revenue integrations are still needed for production financial reporting. |
| Needed | Sonar integration to pull actual customer revenue attribution. Real margin calculation using customer MRR, carrier MRC, facility MRC, transport allocation, and invoice actuals. Full infrastructure waterfall view by asset, parent/child relationship, market, provider, service type, and accounting period. ETF exposure formulas and renewal projection forecasts using contract escalators. |
7. Map Enhancements
| Detail | |
|---|---|
| - | -------- |
| Current | A→Z lines with provider coloring and bandwidth thickness. Provider/type/status filters. |
| Impact | Map is useful but isolated from table view. No external data overlays. |
| Needed | Polygon/lasso selection tool. Shared filter state with circuit table. Wisdm tower layer overlay. Sonar property/coverage layer overlay. Tile hosting decision (MapTiler vs. self-hosted). Cluster markers for dense endpoint areas. |
8. Topology Enhancements
| Detail | |
|---|---|
| - | -------- |
| Current | Endpoint graph with logical/geographic layouts, SPOF detection by node degree. |
| Impact | Layout resets on reload. No true networking detail. |
| Needed | Drag/drop layout with save per user and shared default. True networking fields: VLANs, BGP sessions, router interfaces, handoff ports, IP blocks. Better redundancy modeling (path diversity, not just node degree). |
9. Financial / P&L View
| Detail | |
|---|---|
| - | -------- |
| Current | Implemented with per-circuit modeled P&L, carrier spend, margin, ETF exposure, and the first infrastructure subtended-link economics model. |
| Needed | Sonar revenue attribution, invoice actuals, carrier/customer/market/service rollups, infrastructure waterfall reports, renewal projection forecast, allocation calculators, and export to XLSX. |
10. Address Lookup
| Detail | |
|---|---|
| - | -------- |
| Current | Implemented text search across circuit, carrier, endpoint, city, state, and address fields. |
| Needed | Integration with Xiber Service Address Availability Checker. Nearby endpoint/circuit search by radius. Quote-history cost-to-serve estimate. |
11. Mobile Field View
| Detail | |
|---|---|
| - | -------- |
| Current | Implemented responsive field view with search, one-tap NOC call, copy circuit ID, and map app links. |
| Needed | Add infrastructure asset support, recent events, paired-circuit context, and offline-friendly behavior. |
12. Invoice Ingestion
| Detail | |
|---|---|
| - | -------- |
| Current | Invoice and InvoiceLineItem schemas exist. No ingestion pipeline. |
| Needed | Mailbox polling (M365 Graph) or manual upload. PDF invoice parsing with line item extraction. Automatic matching to circuit by carrier circuit ID. Variance detection (invoiced MRC vs. contracted MRC). Auto-create Monday.com task for finance team on variance. |
13. Vendor Portal Connectors
| Detail | |
|---|---|
| - | -------- |
| Current | Not implemented. |
| Needed | Lumen Control Center API connector. Zayo Tranzact API connector. Cogent portal connector. Vault/Doppler credential storage. Playwright scraping fallback where APIs are unavailable. |
14. MCP Full Coverage
| Detail | |
|---|---|
| - | -------- |
| Current | Token-aware read/context tools exist for search, circuits, infrastructure, customers, RF links, quotes, quote draft queue, carrier summary, renewal pipeline, and site document/photo metadata. Quote draft MCP tools can stage vendor quotes for human review without committing them to quote history. |
| Needed | get_circuit_pl, get_outage_history, broader write tools with explicit agent confirmation flow, and XOS MCP gateway registration/runtime management. |
Recommended Build Phases
| Phase | Focus | Why First |
|---|---|---|
| 1 | Real Entra authentication | Cannot deploy without identity. Blocks audit logging. |
| 2 | Audit logging | Required for compliance and accountability. |
| 3 | Renewal engine + notifications | Highest business value — prevents missed deadlines and auto-renew traps. |
| 4 | Contract CRUD + PDF ingestion | Enables self-service contract management, reduces manual data entry. |
| 5 | Financial/P&L + Sonar integration + infrastructure waterfall | Real margin visibility, accurate business intelligence across circuits, structures, child facilities, and customer endpoints. |
| 6 | Import enhancements (AI mapping, editor) | Reduces friction for bulk data onboarding. |
| 7 | Invoice ingestion + variance detection | Catches billing errors, automates finance workflows. |
| 8 | MCP full coverage | Enables XOS agents to query NetOS data for automated reporting and decisions. |
| 9 | Map + topology enhancements | Improved operational visualization. |
| 10 | Mobile, address lookup, exports | Quality-of-life features for field and sales teams. |
| 11 | Vendor portal connectors | Automated circuit status sync from carrier portals. |
Technical Debt
| Item | Notes |
|---|---|
| Celery workers | Dependencies installed, workers not yet running. Needed for renewal engine and invoice polling. |
| Redis | Running but only used for Celery broker. Could also cache dashboard aggregations. |
| pgvector | Extension installed but no embeddings generated yet. Future use for semantic circuit search. |
| Error handling | API returns generic 500s in some edge cases. Need structured error responses. |
| Test coverage | No automated tests. Need unit tests for import logic, API endpoints, and renewal state machine. |
| CI/CD | No pipeline. Need GitHub Actions or similar for lint, test, build, deploy. |