eced5f8699
Complete docs/engineering/ suite — 12 documents covering company overview, system architecture, tech stack ADRs, codebase structure, service deep dives, annotated code walkthroughs, dev setup, engineering workflow, testing strategy, deployment/ops, SDK guide, and README index. All content verified against source files. All 82 tasks in openspec/changes/engineering-docs/tasks.md marked complete. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
3.2 KiB
3.2 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 8 services/components — purpose, interface, schema, error types | 30 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 4 SDKs — installation, examples, contribution guide | 20 min |
Total estimated reading time for new engineers: ~3.5 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 | 11-sdk-guide.md |
| Understand why a technology was chosen | 03-tech-stack.md |
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)