# 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](01-overview.md) | What SentryAgent.ai builds, why it exists, the product feature set, Phase roadmap | 15 min |
| 2 | [System Architecture](02-architecture.md) | Component diagram, HTTP request lifecycle, OAuth 2.0 data flow, multi-region topology | 20 min |
| 3 | [Technology Stack and ADRs](03-tech-stack.md) | Why each technology was chosen — rationale and alternatives considered | 20 min |
| 4 | [Codebase Structure](04-codebase-structure.md) | Directory map, where to add new code, DRY enforcement rules | 15 min |
| 5 | [Service Deep Dives](05-services.md) | 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](06-walkthroughs.md) | Step-by-step traces of token issuance, agent registration, credential rotation | 30 min |
| 7 | [Development Environment Setup](07-dev-setup.md) | Clone to running local stack — under 30 minutes | 30 min |
| 8 | [Engineering Workflow](08-workflow.md) | OpenSpec spec-first workflow, branching, PR checklist, commit conventions | 20 min |
| 9 | [Testing Strategy](09-testing.md) | Unit vs integration, coverage gates, how to write tests, OWASP reference | 20 min |
| 10 | [Deployment and Operations](10-deployment.md) | Docker, Terraform, Prometheus/Grafana, operational runbook | 20 min |
| 11 | [SDK Integration Guide](11-sdk-guide.md) | 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](04-codebase-structure.md) |
| Run the project locally | [07-dev-setup.md](07-dev-setup.md) |
| Understand how token issuance works end-to-end | [06-walkthroughs.md](06-walkthroughs.md) |
| Add a new API endpoint | [08-workflow.md](08-workflow.md) + [04-codebase-structure.md](04-codebase-structure.md) |
| Write tests | [09-testing.md](09-testing.md) |
| Deploy to production | [10-deployment.md](10-deployment.md) |
| Integrate with the SDK (Node.js, Python, Go, Java, Rust) | [11-sdk-guide.md](11-sdk-guide.md) |
| Understand why a technology was chosen | [03-tech-stack.md](03-tech-stack.md) |
| Understand tier limits and billing | [01-overview.md](01-overview.md) (Section 6) + [03-tech-stack.md](03-tech-stack.md) (ADR-11) |
| Understand AGNTCY compliance reports | [05-services.md](05-services.md) (ComplianceService) |
| Understand the A2A delegation flow | [06-walkthroughs.md](06-walkthroughs.md) (Walkthrough 4) |
| Run the AGNTCY conformance suite | [09-testing.md](09-testing.md) (Section 10.8) |
| Add a new Rust SDK endpoint | [11-sdk-guide.md](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](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 reference
- `docs/agntcy/` — AGNTCY alignment documentation
- `openspec/` — OpenSpec change management (proposals, designs, specs, tasks, archives)