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>
62 lines
3.9 KiB
Markdown
62 lines
3.9 KiB
Markdown
# 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)
|