What is this?

The FabricBloc Developer Hub is the single entry point for engineering context. It replaces scattered Notion pages, Confluence wikis, and bookmarked GitHub links with one dashboard that answers three questions:

1. Is the platform healthy?
2. Am I set up correctly?
3. Where do I find what I need?

How to use it

Overview: Platform health, quick start, architecture, all repositories
Map: Interactive architecture visualization (pan, zoom, click to drill down)
APIs: Service API documentation grouped by layer (Product, Platform, Infrastructure)
Contracts: Solidity smart contract ABIs and deployment data
Events: CloudEvents schema catalog across all services
Tools: Claude Code plugins, MCP server, AI agent access, getting started guides
Infrastructure: Local development infrastructure (Docker, PostgreSQL, Redis, Grafana, Jaeger)
Team: Contributor profiles and activity from GitHub

Key principle: No hardcoded data

Everything on this dashboard comes from generated JSON files produced by the docs pipeline (make generate). Service catalogs, event schemas, contract ABIs, and compliance scores are all derived from the actual codebase -- not manually maintained lists.

The MCP advantage

The FabricBloc MCP server gives Claude access to ALL platform APIs, events, and contracts without cloning every repo. A developer working on one service can ask Claude about any other service's endpoints, events, or contracts through the MCP connection. This eliminates the need to pull 15+ repos on a weak machine.

bun run mcp/server.ts

Phase 2 (shipped)

GitHub API integration -- deploy triggers, CI status, PR activity, contributor profiles
Activity feed -- recent commits, who's working on what

Phase 3 roadmap

Grafana metrics -- service health, error rates, latency pulled from dashboards
Real-time updates -- WebSocket for live health dots (currently snapshot-based)

This dashboard is part of fabricbloc-docs. Source: github.com/BloclabsHQ/fabricbloc-docs
Configuration: docs.config.yaml
Generation: make generate
Local preview: make serve

FabricBloc — Internal Developer Hub

Product Readiness

Hand-declared by the team. Replaces compliance % as the headline because the welfare question is “can a customer do the thing today?” not “what % of static rules pass?” Engineering quality detail is in the section below.

Loading product readiness…

Engineering Quality (compliance scan)

Loading compliance data…

Service Layers

Entry

ConsoleCreator · Dashboard

APIClient · SDK

AI AgentMCP · Session Keys

Gateway

KongJWT · Rate Limit · Quota · HMAC

Platform

Products

Infra

Chains

Ethereum

Polygon

Base L2

Transaction Flow

1. Client sends request

POST /v1/nft/collections/{id}/mint

2. Kong enriches & decides execution mode

Validates JWT, checks quota, signs HMAC
Sets X-Execution-Mode: gasless | caller

3. Product service encodes calldata

fabric-nft, fabric-token, fabric-dao encode the smart contract call.
They never submit transactions. Only produce calldata.

4. Execution fork

Caller pays

Return calldata to client
↓
Client signs with own wallet
↓
Client submits to chain

Gasless

Publish transaction.requested
↓
fabric-bundler consumes event + builds UserOp
↓
fabric-wallet MPC signs (on request)
↓
Bundler submits to EntryPoint
↓
Chain confirms

Key rule: Product services produce calldata. Bundler orchestrates gasless. Wallet signs when asked. These responsibilities never overlap.

...

Interactive Layered

Source ↗

Loading diagram…

Critical path (Creator → Kong → Platform) HTTP gRPC Event (async)

...

Interactive Layered

Grafana

No map data

Run this command, then refresh the page:

make generate

Details

Contracts

Events

Glossary

Platform and business terminology. Use these terms consistently across code, docs, issues, and conversations.

No glossary data yet. Run make generate to build glossary.

Tools

Plugins, MCP servers, AI agents, and quick links for the FabricBloc engineering stack.

Resources

Team, glossary, signing reference, and platform background — all the context that isn’t an API, event, or contract.

Quick Jump

For AI agents

Machine-readable catalog. Single HTML fetch reveals everything via <link rel="alternate"> tags in <head>. The list below mirrors that catalog for humans + crawlers.

Start at sitemap.json for the full inventory. MCP server available for tool-style access (bun run mcp/server.ts, stdio) — no hosting cost, but requires .mcp.json setup. The links above need neither.

GitHub

Effort, quality, and architecture across the platform. 13-week rolling window from every scanned repo.

How to read this page

Platform-wide activity: Weekly commits across every scanned repo, stacked by service category (products, platform, infra, other). Shows whether the team is trending toward product work, platform work, or infra work over time.
Quality × Productivity quadrant: Each dot is a contributor. X axis is raw output (commits + PRs merged + reviews given). Y axis is a quality composite: conventional-commit % + merge rate + cycle time. Dot color is their dominant architecture layer, dot size is lines changed. The dashed lines are the team medians.
Engineering excellence (DORA): Four canonical metrics from the DORA research program. Deploy frequency — how often you ship (elite teams: multiple/day; high: weekly; medium: monthly; low: < monthly). Lead time for changes — time from first commit to production (elite: <1d; high: <1w; medium: <1m; low: >1m). MTTR — time to recover from a failed deploy (elite: <1h; high: <1d; medium: <1w; low: >1w). Change failure rate — % of deploys that required a hotfix or rollback (elite: 0–15%; medium: 16–30%; low: >30%). These are platform-level signals, never attributed to individuals.
Security posture: Dependabot alerts flag vulnerable dependencies in each service. Severity is reported upstream (critical / high / medium / low). Oldest open is the age in days of the longest-unresolved alert for that service — a freshness signal that catches backlogs growing stale. Patched (7d) is the count of alerts resolved in the last week — a throughput signal. Critical and high open counts at the platform level are the riskiest to fix first. This data comes from the same API the drift-finder uses; this view is visibility-only — it does not file issues.
Growth quadrants: Crushing it = high quality + high output. Precision over volume = high quality, small batches. Volume over precision = lots of output, room to polish. Growth opportunity = room to grow on both axes. All framing is growth-oriented — this is a coaching tool, not a scoreboard.
Leaderboards: Three angles on "who's doing the work": total commits, foundation touches (architecture depth), and reviews given (the invisible work that keeps quality high).
Service bus factor: The number of distinct contributors who touched a service in the window. Bus factor 1 means one person owns the whole service — if they take PTO or move on, the service is orphaned. It's a risk metric: the higher, the healthier.
Layer colors: Platform-wide chart (service categories):
■ products ■ platform ■ infra ■ other

Quadrant dots + per-person donuts (DDD layers):
■ api ■ app ■ business ■ foundation ■ other

Data is derived from public git history. Every contributor is visible to the whole team. make analytics refreshes the data.

Platform-wide activity

Engineering excellence

Security posture

Service bus factor

Platform

Runtime topology, network routing, deploy pipelines, and platform guidance that keeps services aligned.

Prerequisites

Three tools required before you can run any FabricBloc service locally.

1Password Desktop

Secrets manager — CLI injects secrets at runtime

Install: brew install --cask 1password
Install CLI: brew install --cask 1password/tap/1password-cli
Enable: Settings → Developer → "Integrate with 1Password CLI"
Verify: op vault list

Tailscale

VPN mesh — resolves internal DNS, RDS, Grafana

Install: brew install --cask tailscale
Connect to FabricBloc network
Split DNS: 10.50.0.2 for rds.amazonaws.com (exit node ON)

Docker Desktop

Container runtime — everything runs in Docker

Install: brew install --cask docker
Clone: git clone BloclabsHQ/fabric-dev-stack
Setup: make setup && make pull
Start: make up

Port Allocation

All services listen on 8094 internally. Docker maps external ports for local dev.

ServiceExternalInternalOwner

Traffic Routing

Two paths into services. External traffic goes through Kong (JWT, rate limits, HMAC). Internal service-to-service uses the ALB (no JWT, HMAC only).

External KONG

                Creator/Client → api.dev.fabricbloc.com

                → JWT validated · Rate limited · HMAC signed

                → Service

Public Services

Internal ALB

                Service A → internal-api:8000

                → VPC only · No JWT · HMAC required

                → Service B

Internal Services

Never route service-to-service calls through Kong. Use the internal ALB or Docker DNS.

Stack Components

▶ Architecture Reference Principles · networking · secrets

Principles

No .env files

Secrets via op run only. Never on disk.

Everything containerized

No local installs. If it's not in docker-compose, it doesn't run.

Infra-agnostic

Docker DNS locally, ALB in prod. Same pattern everywhere.

Network

                  Local: Service A → fabric-events:8094 → Service B

                  Dev/Prod: Service A → internal-api.dev.fabricbloc.com:8000 → Service B

Secrets Flow

Local

                      .env.op.testnet (op:// URIs)

                      ↓ op run

                      Process memory

Deployed

                      1Password ↓ sync-dev.yaml

                      AWS Secrets Manager ↓ Terraform

                      ECS env vars

Never create .env files with real secrets. 1Password and process memory only.

Team

Contributor profiles from GitHub — repos, PRs, recent activity per person. Data from platform-state.json.

No team data yet. Run make generate-state to load GitHub activity.

Network Access

Every URL falls into one of three zones. If you're unsure whether something should be public, it probably shouldn't be.

PUBLIC — Internet-facing TAILSCALE — VPN required INTERNAL — VPC/ALB only

DomainZonePurpose

Route Exposure

Kong routes on api.dev.fabricbloc.com. Host-restricted routes only respond on listed hosts.

ServiceRouteAuthHost Restriction

Service Status

No deploy data yet. Run make generate-state

CI Health

Workflow status across services. Deep analysis in Grafana CI Dashboard.

Full CI Dashboard →

Failure rates · duration P50/P95 · waste ratio · top offenders

▶ Operations Guide Secrets · credentials · redeploy

Secrets flow from 1Password → AWS Secrets Manager → ECS via GitHub Actions in fabric-iac.

1. Add Env Var

Credential management and deployment workflows. Secrets flow from 1Password → AWS Secrets Manager → ECS via GitHub Actions in fabric-iac.

1. Add Env Var

Add a new secret or env var to a service

1Password → vault 01-fabricbloc → item Fabric-{Service}-Env-Dev
Add field (name = ENV_VAR, value = secret)
Update fabric-iac/dev/fabric/terragrunt.hcl — add to secrets block

2. Sync Credentials

Push 1Password secrets → AWS Secrets Manager

gh workflow run sync-dev.yaml

Open in GitHub →

3. Redeploy Dev

Terraform apply → ECS picks up new config

gh workflow run fabric-dev-apply.yml

Requires approval from @vincent or @cris
Open in GitHub →

                1Password vault (01-fabricbloc)

                  ↓  sync-dev.yaml (GitHub Actions)

                AWS Secrets Manager fabric-dev/1password/fabric-{service}

                  ↓  fabric-dev-apply.yml (Terraform)

                ECS Task Definition → container env vars

                Item naming: Fabric-{ServiceName}-Env-{Dev|Prod}

                AWS path: fabric-{stage}/1password/fabric-{service}

References

fabric-iacTerraform infra · secrets sync

GitHub ActionsAll workflows · sync · plan · apply

CI Health DashboardGrafana · GitHub Actions metrics

What is this?

How to use it

Key principle: No hardcoded data

The MCP advantage

Phase 2 (shipped)

Phase 3 roadmap

FabricBloc — Internal Developer Hub

Product Readiness

Engineering Quality (compliance scan)

Latest Activity

No map data

Contracts

Events

Glossary

Quick Jump

For AI agents

Platform-wide activity

Quality × Productivity

Engineering excellence

Security posture

Service bus factor

Prerequisites

Port Allocation

Traffic Routing

Stack Components

Team

Recent Commits

Network Access

Route Exposure

Service Status

CI Health

References

Refresh Data

Sync Specs

What is this?

How to use it

Key principle: No hardcoded data

The MCP advantage

Phase 2 (shipped)

Phase 3 roadmap

FabricBloc — Internal Developer Hub

Product Readiness

Engineering Quality (compliance scan) i

Latest Activity

No map data

Contracts

Events

Glossary

Quick Jump

For AI agents

Platform-wide activity

Quality × Productivity

Engineering excellence what's this?

Security posture what's this?

Service bus factor what's this?

Prerequisites

Port Allocation

Traffic Routing

Stack Components

Team

Recent Commits

Network Access

Route Exposure

Service Status

CI Health

References

Refresh Data

Sync Specs

Engineering Quality (compliance scan)

Engineering excellence

Security posture

Service bus factor