Open Context Graph is a self-hosted, privacy-aware process intelligence platform built from Slack, Jira, and GitHub metadata. It combines fail-closed permission enforcement, private personal timelines, and k-anonymous analytics so teams can improve execution without creating surveillance risk.

• A self-hosted process intelligence platform for engineering and operations teams.
• Built from enterprise metadata streams (Slack, Jira, GitHub), not employee surveillance.
• Privacy-first by design: fail-closed permissions, private personal views, k-anonymous aggregation.

• This is an AI-engineering system, not only dashboarding: it has a dedicated intelligence layer on top of deterministic ingestion.
• AI today:
  • semantic step labeling for process states
  • probabilistic next-step scoring for operational guidance
  • context-aware clustering support for variants and bottlenecks
• AI roadmap:
  • LLM-assisted natural-language querying of process data
  • richer semantic summarization of critical flows and risk signals
• Guardrails:
  • feature-flagged AI components
  • fail-closed permissions and k-anonymous publishing stay authoritative
  • no raw-content dependency required for baseline value

Overview:

Sales-to-Delivery handoff:

flowchart LR
  subgraph UserLayer["User Layer"]
    Browser["Browser UI<br/>(Overview/Admin/Analytics/Personal)"]
  end

  subgraph AppLayer["Application Layer"]
    UI["Next.js Frontend"]
    API["FastAPI API<br/>Auth + Query + Policy"]
    Workers["Worker Runtime<br/>Ingest + Personal + Aggregation"]
  end

  subgraph Intelligence["AI / Intelligence Layer"]
    Labeling["Semantic Labeling<br/>(LLM optional)"]
    Reasoning["Process Reasoning<br/>and Next-Step Scoring"]
    Similarity["Similarity / Clustering<br/>for Pattern Discovery"]
  end

  subgraph DataLayer["Data Layer"]
    PG[("PostgreSQL<br/>events + graph + aggregates")]
    RQ[("Redis<br/>job queues")]
  end

  subgraph External["External Systems"]
    OIDC["OIDC Provider"]
    Tools["Slack / Jira / GitHub"]
  end

  subgraph Observe["Observability"]
    Prom["Prometheus + Grafana"]
  end

  Browser --> UI
  UI --> API
  API --> OIDC
  API --> PG
  API --> RQ
  API --> Reasoning
  Workers --> RQ
  Workers --> PG
  Workers --> Labeling
  Workers --> Similarity
  Reasoning --> PG
  Labeling --> PG
  Similarity --> PG
  Workers --> Tools
  API --> Prom
  Workers --> Prom
  Labeling --> Prom
  Reasoning --> Prom
  Similarity --> Prom

Legacy note: Table of contents intentionally removed for skim-first README flow.

Prerequisites:

• Docker + Docker Compose
• Make

Start services:

docker compose up -d postgres redis api workers scheduler ui

Initialize database and demo data:

docker compose exec api ocg migrate up
docker compose exec api ocg seed demo

Validate health:

curl -f http://127.0.0.1:8080/healthz
curl -f http://127.0.0.1:8080/readyz

Open interfaces:

• UI: http://127.0.0.1:3000
• API docs: http://127.0.0.1:8080/docs
• Metrics: http://127.0.0.1:8080/metrics

Backend:

python -m pip install -e "backend[dev]"
PYTHONPATH=backend python -m ocg.cli migrate up
PYTHONPATH=backend uvicorn ocg.main:app --host 127.0.0.1 --port 8080 --reload

Frontend:

npm --prefix frontend install
npm --prefix frontend run dev

Use one anchor command for all verification:

• Fast profile: make check CHECK_PROFILE=fast
• CI-equivalent profile: make check CHECK_PROFILE=ci
• Full profile: make check CHECK_PROFILE=full

CHECK_PROFILE=ci|full is strict. Required checks and toolchains cannot silently skip.

The quality pipeline covers:

• format
• lint (+ docs guard)
• typecheck
• frontend production build (ci/full)
• unit + integration tests (profile-gated)
• migration checks
• secret and redaction scans
• OpenAPI compatibility (ci/full)

PYTHONPATH=backend python -m ocg.cli worker run
PYTHONPATH=backend python -m ocg.cli worker scheduler --once
PYTHONPATH=backend python -m ocg.cli worker stats

• Health and metrics:
  • GET /healthz
  • GET /readyz
  • GET /metrics
• Admin:
  • /api/v1/admin/connectors/*
• Personal:
  • /api/v1/personal/timeline
  • /api/v1/personal/tasks
  • /api/v1/personal/opt_in_aggregation
• Analytics:
  • /api/v1/analytics/processes/*
  • /api/v1/analytics/patterns/*
• Suggestions:
  • POST /api/v1/suggest/next_steps

• Fail-closed permissions: unknown ACL state is excluded from user-visible output.
• OIDC validation is mandatory for non-local bind startup.
• Raw-content ingestion is disabled by default.
• Aggregate analytics publish only at or above k-anonymity threshold.
• Dev header auth mode is disabled by default and intended for local/demo workflows only.

• Request trace correlation via X-Trace-Id and traceparent.
• Prometheus metrics on /metrics.
• Dashboards and alerts under ops/grafana/ and ops/prometheus/.

1. Create a branch from main.
2. Keep changes scoped and update SSOT docs when critical surfaces change.
3. Run make check CHECK_PROFILE=ci locally.
4. Open a PR with explicit evidence pointers for acceptance criteria.

• Specs and architecture contracts: spec/
• Decision and assumption logs: DECISIONS.md, ASSUMPTIONS.md
• Session/protocol and governance rules: AGENTS.md, CONSTITUTION.md
• Integrity and checks: MANIFEST.sha256, checks/CHECKS_INDEX.md