# AWS Bedrock LLM Proxy - Documentation Index

## Quick Start

**New to this project?** Start here:
1. Read [QUICK-REFERENCE.md](QUICK-REFERENCE.md) — 5-minute overview
2. Check [implementation-checklist.md](implementation-checklist.md) — What to build, phase by phase
3. Dive into [bedrock-proxy-implementation-plan.md](bedrock-proxy-implementation-plan.md) — Complete technical details

---

## Documentation Files

### 1. [QUICK-REFERENCE.md](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](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](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:

```bash
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](implementation-checklist.md)
- **"How does auth work?"** → [bedrock-proxy-implementation-plan.md](bedrock-proxy-implementation-plan.md#part-3-dual-auth-middleware)
- **"What's the config?"** → [QUICK-REFERENCE.md](QUICK-REFERENCE.md#-configuration)
- **"Show me the code"** → [bedrock-proxy-implementation-plan.md](bedrock-proxy-implementation-plan.md#part-4-openai-v1-api-implementation)

---

## 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