Factory Intelligence Platform

Open-source infrastructure for intelligent, connected, and AI-ready factories.

Factory Intelligence Platform is an Open Factory Initiative project for a modular Factory Intelligence Layer. The platform consumes factory observations, normalizes them into FactoryEvents, detects operational and quality risk, shows evidence-backed investigation context, and supports governed human-reviewed recommendation workflows.

Status: early-stage open-source project. The current direction is a Docker Compose microservices runtime that consumes external Demo-Factory protocol data through read-only connectors.

Runtime Direction

Demo-Factory is now the separate local source/simulation repository. This repository owns the intelligence platform runtime:

Demo-Factory protocols
-> FIP read-only connector worker
-> FactoryEvent ingestion and storage
-> Process Sentinel worker
-> FastAPI API
-> Next.js Operations Workbench

The in-repo generator and demo targets remain as legacy fixtures for tests and backward-compatible local checks. They are not the default FIP runtime path.

Target Architecture

flowchart LR
    subgraph Sources["External Factory Data Sources"]
        DF["Demo-Factory protocol services"]
        OPC["OPC-UA"]
        MQTT["MQTT"]
        BAC["BACnet"]
        MES["MES / QMS / CMMS / ERP"]
    end

    subgraph Platform["Factory Intelligence Platform"]
        Connectors["Read-only connector workers"]
        Events["Unified FactoryEvent model"]
        Store["Postgres event store"]
        Sentinel["Process Sentinel"]
        Evidence["Evidence timeline"]
        Governance["Governed recommendations"]
        API["FastAPI API"]
        UI["Operations Workbench"]
    end

    Sources --> Connectors
    Connectors --> Events
    Events --> Store
    Store --> Sentinel
    Sentinel --> Evidence
    Evidence --> Governance
    Governance --> API
    API --> UI

Loading

Current Repository Shape

apps/web                  Next.js Operations Workbench
services/api              FastAPI endpoints over FIP state
services/ingestion        Event validation and read-only protocol adapters
services/process-sentinel Drift rules, evidence, recommendations, state store
services/simulator        Legacy local fixture code, not the default runtime
packages/factory-events   Shared event and connection profile contracts
packages/test-fixtures    Contract and connector fixture data
infra/docker              Local Compose configuration
docs                      Architecture, safety, runtime, and contributor docs
prompts                   Codex implementation prompts

Safety Boundary

FIP is read-only by default for industrial protocols. It must not:

• write to PLCs, DCS, SCADA, OPC-UA nodes, MQTT topics, BACnet objects, or equipment controllers;
• perform arbitrary tag writes;
• change machine parameters;
• release, quarantine, hold, or otherwise disposition product;
• write to QMS/MES records;
• claim production readiness, validated GxP use, electronic signatures, or compliance validation from local development fixtures.

See docs/CONNECTOR_SAFETY_MODEL.md for the current connector safety model.

Local Runtime Commands

The Compose runtime from epic #232 is the current local integration path. Start Demo-Factory separately when validating external local protocol sources:

cd ../Demo-Factory
docker compose up -d --build

Start the FIP Compose stack from this repository:

cd ../Factory-Intelligence-Platform
make compose-up
make compose-ps
make compose-logs
curl http://localhost:8000/health
make compose-down

Smoke test the composed runtime before opening Docker runtime PRs:

make compose-smoke

The smoke target uses FIP host ports 18000 and 13000 so it can run while the full Demo-Factory stack owns ports 8000 and 3000.

The wrappers call docker compose -f infra/docker/docker-compose.yml .... The equivalent direct commands are:

docker compose -f infra/docker/docker-compose.yml up --build
docker compose -f infra/docker/docker-compose.yml ps
docker compose -f infra/docker/docker-compose.yml logs -f
docker compose -f infra/docker/docker-compose.yml down

Use docker compose down for normal shutdown. Use docker compose -f infra/docker/docker-compose.yml down -v only when you intentionally want to delete FIP named volumes, such as local Postgres data.

The FIP Compose stack includes postgres, api, web, connector-worker, and sentinel-worker. It does not start an in-repo simulator container. Contributors can still run the API and Workbench directly for focused development:

make setup
make api
cd apps/web
npm run dev

Open:

http://127.0.0.1:8000/docs
http://127.0.0.1:3000

Documentation

• docs/DEMO_RUNBOOK.md - current Docker/Demo-Factory runtime direction and transition notes.
• docs/runtime/DOCKER_COMPOSE.md - detailed Docker Compose startup, shutdown, rebuild, logs, health-check, and reset commands.
• docs/runtime/TROUBLESHOOTING.md - Docker daemon, port, Postgres, connector, API, and Workbench troubleshooting.
• docs/demo/OPERATIONS_WORKBENCH_DEMO_RUNBOOK.md - Workbench runtime notes for the operator console.
• docs/demo/MANUFACTURER_DEMO_RUNBOOK.md - manufacturer discussion framing.
• docs/demo/TROUBLESHOOTING.md - runtime troubleshooting checks.
• docs/DEVELOPMENT.md - local development workflow.
• docs/ARCHITECTURE.md - platform architecture and connector boundaries.
• docs/CONNECTOR_SAFETY_MODEL.md - read-only connector safety model.
• docs/TESTING.md - test strategy and commands.
• docs/START_HERE_FOR_CODEX.md - Codex workflow entry point.

Validation

Run these before opening a pull request:

docker compose -f infra/docker/docker-compose.yml config
make compose-config
make compose-smoke
make lint
make typecheck
make test
cd apps/web
npm test
npm run lint
npm run typecheck

Working With Codex

Start with docs/START_HERE_FOR_CODEX.md. Ask Codex to inspect the current repository and issue before editing, keep work scoped to one issue, add or update tests, and update docs/LEARNING_LOG.md after meaningful changes.

Contributing

New contributors should start with CONTRIBUTING.md. The project foundation status is summarized in docs/PROJECT_FOUNDATION.md.

License

This project uses the repository license in LICENSE.