Fabric4L Engineering

Welcome to the Fabric4L Engineering documentation — the technical source of truth for developers, operators, and security engineers working on the ValuePact platform.

Audience

This section is intended for platform engineers, SREs, security engineers, and technical contributors. End-user product documentation lives in the other top-level sections (Getting Started, User Guides, Administration, etc.).

What is Fabric4L?

Fabric4L is the internal engineering codename for the six-layer data and intelligence pipeline that powers ValuePact:

Layer	Service	Port	Responsibility
L1	layer1-ingestion	8001	Playwright crawling, Celery jobs, Redis queues, compliance-aware ingestion
L2	layer2-extraction	8002	Pydantic v2 extraction, LLM extraction, RDF/OWL generation, provenance
L3	layer3-knowledge	8003	Neo4j, GraphRAG, hybrid retrieval, pgvector, subgraph APIs
L4	layer4-agents	8004	LangGraph workflows, ROI calculator, business case generation, checkpoints
L5	layer5-ground-truth	8005	TruthObject validation, maturity ladder, evidence-backed claims
L6	layer6-benchmarks	8006	Peer comparison, statistical validation, datasets, benchmark policies

The frontend (React + Vite) communicates with these layers through a shared API gateway and TanStack Query.

Documentation Sections

Architecture

System design, data flow, service topology, auth architecture, tenancy model, and observability stack.

• System Overview — Six-layer pipeline and technology stack
• Service Map — Ports, responsibilities, and runtime paths
• Data Flow — How requests flow through L1→L2→L3→L4→L5→L6
• Authentication — OIDC, RBAC, and service-to-service auth
• Tenancy — Multi-tenant isolation strategy
• Observability — Logging, metrics, traces, and alerting

Development

Setup instructions, contribution guidelines, coding standards, testing strategy, and repo organization.

• Contribution Guide — First-time setup, commits, PRs
• Coding Standards — Python, TypeScript, and layer-boundary rules
• Testing — Behavior-first testing, markers, and coverage
• Repo Strategy — Monorepo structure and canonical paths

Operations

Deployment procedures, monitoring, incident response, and operational runbooks.

• Deployment — Docker Compose, Kubernetes, and migrations
• Monitoring — Health checks, logs, metrics, and dashboards
• Incident Response — Severity levels and playbooks
• Runbooks — Common operational procedures

Security

Auth boundaries, tenant isolation, secret management, threat model, and production-readiness gates.

• Auth Boundaries — Token validation and RBAC
• Tenant Isolation — Cross-tenant prevention patterns
• Secret Management — Infisical, CI/CD, and rotation
• Threat Model — OWASP coverage and controls
• Readiness Gates — What blocks production deployment

Behavior Contracts

Behavior-first testing philosophy, critical behaviors, test strategy, and readiness gates.

• Critical Behaviors — What must be tested
• Test Strategy — Test pyramid and markers
• Gate Registry — Four-stage readiness ladder

ADRs

Architecture Decision Records for major technical choices.

Reference

Glossary, quick-reference links, and documentation standards.

Quick Commands

# Full verification (run before every PR)
make verify

# Run all backend tests
make test

# Run contract tests
make contract-tests

# Check for conflict markers
make check-conflict-markers

# Check migration heads
make check-migration-heads

# Production readiness gate
make production-readiness-gate

Core Principles

1. Contract-first — APIs, schemas, and agent outputs are the source of truth.
2. Tenant-safe — Every data operation is scoped by authenticated tenant context.
3. Layered — Logic stays in its layer; cross-layer calls use defined contracts.
4. Auditable — All critical actions emit structured audit events.
5. Provider-agnostic — Core orchestration has no hardcoded LLM vendor logic.
6. Drift-resistant — Contracts, types, and tests prevent silent architectural drift.

Getting Help

• Engineering questions: #engineering Slack channel
• Security incidents: Follow the Incident Response Playbook
• On-call issues: See Runbooks
• Documentation gaps: File a ticket and add a TODO(behavior-debt) comment in code