Distilled from docs/ARCHITECTURE.md in black-candle-technologies/Sentinel.
Defines the technical architecture for the internal static analysis platform: system components, data flow, deployment models, storage, MCP support, and automation for GitHub/Linear issue creation.
The platform analyzes source repositories for maintainability, reliability, architecture, security, and change-risk findings, with local, CI, dashboard, and AI-agent access to results.
Primary:
- Modular analyzer architecture with language-specific rule packs
- Low-latency local and changed-files workflows
- Stable and queryable findings model
- Batch scanning and incremental analysis
- Built-in MCP server for Codex, Claude Code, and other MCP clients
- Reliable issue automation with deduplication and lifecycle sync
- Safe handling of sensitive findings such as secrets
Secondary:
- Gradual rollout from report-only to enforcement
- Long-term trend and hotspot analysis
- Scale across many repositories
- Platform teams can add rules and integrations without major rewrites
- CLI / Local Runtime — runs scans locally, serves the local MCP server, supports changed-files analysis.
- Analysis Engine — parses source code, builds semantic structures, runs rules, produces findings.
- Policy Engine — applies thresholds, suppressions, severity mappings, gating, architecture rules, and ticketing policies.
- Graph / Hotspot Engine — builds dependency graphs and computes hotspot scores using complexity, churn, and centrality.
- Result Store — persists scans, findings, fingerprints, trend data, linked external issues, and suppressions.
- Issue Automation — creates GitHub/Linear issues for high/critical vulnerabilities with deduplication.
Source repo → CLI → Analysis Engine (parse → rules → findings)
→ Policy Engine (thresholds, suppressions, severity)
→ Result Store (scans, findings, fingerprints)
→ Issue Automation (deduplicated GitHub/Linear issues)
→ MCP Server (findings + remediation guidance for AI agents)
- Local: developer runs scans on their machine; MCP server serves Claude Code / Codex locally.
- CI: scans full repos or changed files in pull requests; gates on policy.
- Scheduled: periodic full-repo scans feeding trend and hotspot analysis.
SQLite for scan history, findings, fingerprints, and suppressions in v1. Findings carry stable fingerprints so the same issue is recognized across scans (deduplication for issue automation).
¶ Security handling
Secrets detected by rules are handled carefully: findings are flagged without spreading secret values, and issue automation avoids leaking sensitive content into trackers.
See also: Sentinel overview · Rule spec