8cabc0191c
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.9 KiB
3.9 KiB
SentryAgent.ai — Engineering Knowledge Base
Internal reference for engineers contributing to AgentIdP. Read in order if you're new. Jump to the relevant document if you know what you need.
Reading Order (New Engineers Start Here)
| # | Document | What you'll learn | Time |
|---|---|---|---|
| 1 | Company and Product Overview | What SentryAgent.ai builds, why it exists, the product feature set, Phase roadmap | 15 min |
| 2 | System Architecture | Component diagram, HTTP request lifecycle, OAuth 2.0 data flow, multi-region topology | 20 min |
| 3 | Technology Stack and ADRs | Why each technology was chosen — rationale and alternatives considered | 20 min |
| 4 | Codebase Structure | Directory map, where to add new code, DRY enforcement rules | 15 min |
| 5 | Service Deep Dives | All 17 services/components (incl. Phase 3–6: AnalyticsService, TierService, ComplianceService, FederationService, DIDService, WebhookService, BillingService, DelegationService, OIDCService) — purpose, interface, schema, error types | 45 min |
| 6 | Annotated Code Walkthroughs | Step-by-step traces of token issuance, agent registration, credential rotation | 30 min |
| 7 | Development Environment Setup | Clone to running local stack — under 30 minutes | 30 min |
| 8 | Engineering Workflow | OpenSpec spec-first workflow, branching, PR checklist, commit conventions | 20 min |
| 9 | Testing Strategy | Unit vs integration, coverage gates, how to write tests, OWASP reference | 20 min |
| 10 | Deployment and Operations | Docker, Terraform, Prometheus/Grafana, operational runbook | 20 min |
| 11 | SDK Integration Guide | All 5 SDKs (Node.js, Python, Go, Java, Rust) — installation, examples, contribution guide | 25 min |
Total estimated reading time for new engineers: ~4 hours
Quick Reference
| I need to... | Go to |
|---|---|
| Understand the codebase layout | 04-codebase-structure.md |
| Run the project locally | 07-dev-setup.md |
| Understand how token issuance works end-to-end | 06-walkthroughs.md |
| Add a new API endpoint | 08-workflow.md + 04-codebase-structure.md |
| Write tests | 09-testing.md |
| Deploy to production | 10-deployment.md |
| Integrate with the SDK (Node.js, Python, Go, Java, Rust) | 11-sdk-guide.md |
| Understand why a technology was chosen | 03-tech-stack.md |
| Understand tier limits and billing | 01-overview.md (Section 6) + 03-tech-stack.md (ADR-11) |
| Understand AGNTCY compliance reports | 05-services.md (ComplianceService) |
| Understand the A2A delegation flow | 06-walkthroughs.md (Walkthrough 4) |
| Run the AGNTCY conformance suite | 09-testing.md (Section 10.8) |
| Add a new Rust SDK endpoint | 11-sdk-guide.md (Section 6 contribution guide) |
Document Conventions
- File paths are always relative to the project root unless otherwise noted.
- Line numbers in 06-walkthroughs.md were verified against commit
1f95cfe. - Code examples are complete and runnable — no ellipses, no placeholders.
- ADR stands for Architecture Decision Record — a short document recording a technology choice.
Related Documentation
docs/developers/— End-user API reference (for agents calling the AgentIdP API)docs/devops/— Operator runbooks and environment variable referencedocs/agntcy/— AGNTCY alignment documentationopenspec/— OpenSpec change management (proposals, designs, specs, tasks, archives)