testing-proxy/docs/README.md

AWS Bedrock LLM Proxy - Documentation Index

Quick Start

New to this project? Start here:

1. Read QUICK-REFERENCE.md — 5-minute overview
2. Check implementation-checklist.md — What to build, phase by phase
3. Dive into bedrock-proxy-implementation-plan.md — Complete technical details

---

Documentation Files

1. QUICK-REFERENCE.md

Purpose: High-level architecture overview & quick answers

• What you're building (1 sentence)
• Architecture diagram
• Config structure
• Dual auth examples
• OpenAI endpoints
• Spending limits
• Key files list
• Pre-flight checklist
• Error responses

Read this first — 10 minutes

---

2. implementation-checklist.md

Purpose: Task breakdown & day-by-day progress tracking

• Phase 1 (MVP) — Days 1-3
• Phase 2 (Multi-model) — Days 4-6
• Phase 3 (Admin) — Optional
• Key technical tasks
• QA matrix
• Config requirements

Use this to track progress — 5 minutes to skim, refer back daily

---

3. bedrock-proxy-implementation-plan.md

Purpose: Complete implementation guide with code examples

• Part 1: Architecture overview
• Part 2: Configuration system (Docker secret, OAuth discovery)
• Part 3: Dual auth middleware (JWT + Bearer detection)
• Part 4: OpenAI v1 API implementation
• Part 5: Spending enforcement
• Part 6: Database schema
• Part 7: Implementation phases
• Part 8: Testing & QA

Use this while coding — Reference as needed

---

Architecture Decision Record

See ../AGENTS.md for:

• Final architecture decisions (all 10 requirements)
• Configuration approach
• OAuth discovery integration
• Dual auth implementation
• OpenAI compatibility decisions

---

Key Files to Create (Phase 1)

src/
├── lib/
│   ├── config/
│   │   └── loader.js          ← Load config + fetch OAuth discovery
│   ├── auth/
│   │   └── middleware.js       ← Token detection + validation
│   ├── bedrock/
│   │   ├── client.js           ← AWS SDK wrapper
│   │   └── models.js           ← Model registry + pricing
│   └── spending/
│       └── enforcer.js         ← Cost estimation + atomic deduction
├── routes/
│   └── api/v1/
│       ├── chat/completions/
│       │   └── +server.js      ← Main endpoint (POST)
│       └── models/
│           └── +server.js      ← Model list (GET)
└── hooks.server.js             ← Auth middleware integration

---

Before You Start

✅ Prerequisites:

• AWS IAM user with bedrock:InvokeModel permission
• PostgreSQL database
• Verify OAuth discovery: curl https://data.titleproject.space/.well-known/oauth-authorization-server
• title-graphql introspection endpoint working

---

Phase 1 Success Criteria

When complete, this should work:

curl -X POST http://localhost:3000/api/v1/chat/completions \
  -H "Authorization: Bearer <JWT_or_Bearer_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-haiku-20240307",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Returns OpenAI-format response with usage tokens

---

Getting Help

• "What should I build?" → implementation-checklist.md
• "How does auth work?" → bedrock-proxy-implementation-plan.md
• "What's the config?" → QUICK-REFERENCE.md
• "Show me the code" → bedrock-proxy-implementation-plan.md

---

Navigation

All documentation files are in this directory (docs/). Files reference each other with relative links:

• ./bedrock-proxy-implementation-plan.md
• ./implementation-checklist.md
• ./QUICK-REFERENCE.md

---

Last Updated: June 27, 2026