mirror of
https://github.com/tiennm99/claude-central-gateway.git
synced 2026-04-17 15:20:33 +00:00
docs: Add comprehensive documentation suite
- Project overview, system architecture, code standards - API reference with 15+ examples - Quick start guide with troubleshooting - Updated README with feature highlights and compatibility matrix
This commit is contained in:
217
docs/index.md
Normal file
217
docs/index.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Documentation Index
|
||||
|
||||
Welcome to Claude Central Gateway documentation. Start here to find what you need.
|
||||
|
||||
## Getting Started
|
||||
|
||||
**New to the project?** Start with these:
|
||||
|
||||
1. **[Quick Start](./quick-start.md)** (5 min read)
|
||||
- Deploy the gateway in 1 minute
|
||||
- Configure Claude Code
|
||||
- Verify it works
|
||||
- Troubleshooting tips
|
||||
|
||||
2. **[Project Overview & PDR](./project-overview-pdr.md)** (10 min read)
|
||||
- What this project does and why
|
||||
- Feature requirements and roadmap
|
||||
- When to use it (and when not to)
|
||||
|
||||
## API & Integration
|
||||
|
||||
**Building with the gateway?** Use these:
|
||||
|
||||
3. **[API Reference](./api-reference.md)** (20 min read)
|
||||
- Complete endpoint documentation
|
||||
- Request/response formats
|
||||
- Authentication details
|
||||
- Code examples (curl, JavaScript)
|
||||
- Error handling
|
||||
|
||||
## Technical Deep Dives
|
||||
|
||||
**Understanding the architecture?** Read these:
|
||||
|
||||
4. **[System Architecture](./system-architecture.md)** (15 min read)
|
||||
- Request/response flow with diagrams
|
||||
- Tool use round-trip workflow
|
||||
- Data structures and schemas
|
||||
- Deployment topology
|
||||
- Stop reason mapping
|
||||
- Scalability characteristics
|
||||
|
||||
5. **[Code Standards](./code-standards.md)** (15 min read)
|
||||
- Codebase structure and module responsibilities
|
||||
- Naming conventions
|
||||
- Authentication implementation
|
||||
- Error handling patterns
|
||||
- Security practices
|
||||
- Performance considerations
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Deploy the Gateway
|
||||
→ [Quick Start](./quick-start.md#deploy-to-vercel)
|
||||
|
||||
### Configure Claude Code
|
||||
→ [Quick Start](./quick-start.md#configure-claude-code)
|
||||
|
||||
### Make API Requests
|
||||
→ [API Reference](./api-reference.md#usage-examples)
|
||||
|
||||
### Understand Tool Use
|
||||
→ [System Architecture](./system-architecture.md#tool-use-round-trip-special-case)
|
||||
|
||||
### Map Models to Cheaper Providers
|
||||
→ [API Reference](./api-reference.md#configuration) or [Quick Start](./quick-start.md#cost-optimization-tips)
|
||||
|
||||
### Debug Issues
|
||||
→ [Quick Start](./quick-start.md#troubleshooting)
|
||||
|
||||
### Understand Data Flow
|
||||
→ [System Architecture](./system-architecture.md#request-flow-detailed)
|
||||
|
||||
### Review Implementation Details
|
||||
→ [Code Standards](./code-standards.md)
|
||||
|
||||
## Documentation Map
|
||||
|
||||
```
|
||||
docs/
|
||||
├── index.md ← You are here
|
||||
├── quick-start.md ← Start here (5 min)
|
||||
├── project-overview-pdr.md ← What & why (10 min)
|
||||
├── api-reference.md ← API details (20 min)
|
||||
├── system-architecture.md ← How it works (15 min)
|
||||
└── code-standards.md ← Code details (15 min)
|
||||
```
|
||||
|
||||
## Search by Topic
|
||||
|
||||
### Authentication & Security
|
||||
- See [Code Standards: Security Practices](./code-standards.md#security-practices)
|
||||
- See [API Reference: Authentication](./api-reference.md#authentication)
|
||||
|
||||
### Streaming Responses
|
||||
- See [System Architecture: Response Transformation](./system-architecture.md#response-transformation)
|
||||
- See [API Reference: Response (Streaming)](./api-reference.md#response-streaming)
|
||||
|
||||
### Tool Use / Function Calling
|
||||
- See [System Architecture: Tool Use Round-Trip](./system-architecture.md#tool-use-round-trip-special-case)
|
||||
- See [API Reference: Tool Definition](./api-reference.md#tool-definition)
|
||||
- See [Code Standards: transform-response.js](./code-standards.md#transform-responsejs)
|
||||
|
||||
### Image Support
|
||||
- See [API Reference: Image Content Type](./api-reference.md#image-user-messages-only)
|
||||
- See [System Architecture: Content Block Handling](./system-architecture.md#content-block-handling)
|
||||
|
||||
### Error Handling
|
||||
- See [API Reference: Error Responses](./api-reference.md#error-responses)
|
||||
- See [Code Standards: Error Handling](./code-standards.md#error-handling)
|
||||
- See [Quick Start: Troubleshooting](./quick-start.md#troubleshooting)
|
||||
|
||||
### Model Mapping & Configuration
|
||||
- See [API Reference: Configuration](./api-reference.md#configuration)
|
||||
- See [Quick Start: Model Mapping Examples](./quick-start.md#model-mapping-examples)
|
||||
|
||||
### Deployment Options
|
||||
- See [Quick Start: Deploy to Vercel](./quick-start.md#deploy-to-vercel)
|
||||
- See [Quick Start: Cloudflare Workers](./quick-start.md#cloudflare-workers)
|
||||
- See [System Architecture: Deployment Topology](./system-architecture.md#deployment-topology)
|
||||
|
||||
### Stop Reasons & Generation Control
|
||||
- See [API Reference: Stop Reasons](./api-reference.md#stop-reasons)
|
||||
- See [System Architecture: Stop Reason Mapping](./system-architecture.md#stop-reason-mapping)
|
||||
- See [Code Standards: transform-response.js](./code-standards.md#transform-responsejs)
|
||||
|
||||
### Performance & Scalability
|
||||
- See [System Architecture: Scalability Characteristics](./system-architecture.md#scalability-characteristics)
|
||||
- See [Code Standards: Performance Considerations](./code-standards.md#performance-considerations)
|
||||
|
||||
### Future Roadmap & Limitations
|
||||
- See [Project Overview: Feature Roadmap](./project-overview-pdr.md#feature-roadmap)
|
||||
- See [Project Overview: Known Limitations](./project-overview-pdr.md#known-limitations)
|
||||
- See [API Reference: Limitations & Compatibility](./api-reference.md#limitations--compatibility)
|
||||
|
||||
## Document Statistics
|
||||
|
||||
| Document | Length | Focus | Audience |
|
||||
|----------|--------|-------|----------|
|
||||
| Quick Start | 5 min | Getting started | Everyone |
|
||||
| Project Overview | 10 min | Vision & requirements | Product, decision makers |
|
||||
| API Reference | 20 min | Endpoints & examples | Developers integrating |
|
||||
| System Architecture | 15 min | Design & flow | Developers, maintainers |
|
||||
| Code Standards | 15 min | Implementation details | Developers, contributors |
|
||||
|
||||
## Learning Paths
|
||||
|
||||
### "I Just Want to Use It"
|
||||
1. [Quick Start](./quick-start.md) - Deploy and configure
|
||||
2. [API Reference](./api-reference.md#usage-examples) - Code examples
|
||||
3. [Quick Start Troubleshooting](./quick-start.md#troubleshooting) - If issues arise
|
||||
|
||||
### "I Want to Understand How It Works"
|
||||
1. [Project Overview](./project-overview-pdr.md) - Context
|
||||
2. [System Architecture](./system-architecture.md) - Design
|
||||
3. [Code Standards](./code-standards.md) - Implementation
|
||||
|
||||
### "I'm Contributing to the Project"
|
||||
1. [Project Overview](./project-overview-pdr.md) - Requirements
|
||||
2. [Code Standards](./code-standards.md) - Structure & conventions
|
||||
3. [System Architecture](./system-architecture.md) - Data flow
|
||||
4. Read the actual code in `src/`
|
||||
|
||||
### "I'm Debugging an Issue"
|
||||
1. [Quick Start Troubleshooting](./quick-start.md#troubleshooting) - Common fixes
|
||||
2. [API Reference](./api-reference.md#error-responses) - Error codes
|
||||
3. [System Architecture](./system-architecture.md#error-handling-architecture) - Error flow
|
||||
4. [Code Standards](./code-standards.md#error-handling) - Error patterns
|
||||
|
||||
## Quick Links
|
||||
|
||||
- **GitHub Repository**: https://github.com/tiennm99/claude-central-gateway
|
||||
- **Deploy to Vercel**: https://vercel.com/new/clone?repository-url=https://github.com/tiennm99/claude-central-gateway
|
||||
- **OpenAI API Documentation**: https://platform.openai.com/docs/api-reference
|
||||
- **Anthropic API Documentation**: https://docs.anthropic.com/en/docs/about/api-overview
|
||||
- **Claude Code Router** (local alternative): https://github.com/musistudio/claude-code-router
|
||||
- **LiteLLM** (enterprise alternative): https://github.com/BerriAI/litellm
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Where do I start?**
|
||||
A: [Quick Start](./quick-start.md) if you want to deploy immediately, or [Project Overview](./project-overview-pdr.md) if you want context first.
|
||||
|
||||
**Q: How do I make API calls?**
|
||||
A: [API Reference](./api-reference.md#usage-examples)
|
||||
|
||||
**Q: Why did my request fail?**
|
||||
A: [Quick Start Troubleshooting](./quick-start.md#troubleshooting) or [API Reference: Error Responses](./api-reference.md#error-responses)
|
||||
|
||||
**Q: How does tool use work?**
|
||||
A: [System Architecture: Tool Use Round-Trip](./system-architecture.md#tool-use-round-trip-special-case)
|
||||
|
||||
**Q: What's supported?**
|
||||
A: [README Features Section](../README.md#features--compatibility) or [API Reference](./api-reference.md#fully-supported)
|
||||
|
||||
**Q: How do I optimize costs?**
|
||||
A: [Quick Start Cost Optimization Tips](./quick-start.md#cost-optimization-tips)
|
||||
|
||||
**Q: Can I self-host?**
|
||||
A: Yes, see [Quick Start Alternative Deployments](./quick-start.md#alternative-deployments)
|
||||
|
||||
## Contributing
|
||||
|
||||
Want to contribute? Start with [Code Standards](./code-standards.md) to understand the architecture, then read the source code in `src/`.
|
||||
|
||||
## Version History
|
||||
|
||||
- **v1.0** (2025-04-05): Hono refactor with full tool use support, streaming, authentication
|
||||
- **v0.x**: Initial OpenAI proxy implementation
|
||||
|
||||
## Last Updated
|
||||
|
||||
April 5, 2025
|
||||
|
||||
---
|
||||
|
||||
**Ready to get started?** → [Quick Start Guide](./quick-start.md)
|
||||
Reference in New Issue
Block a user