feat: documentation revamp

core/schemas/bifrost.go

@@ -426,7 +426,7 @@ type BifrostError struct {
 	IsBifrostError bool       `json:"is_bifrost_error"`
 	StatusCode     *int       `json:"status_code,omitempty"`
 	Error          ErrorField `json:"error"`
-	AllowFallbacks *bool      `json:"allow_fallbacks,omitempty"` // Optional: Controls fallback behavior (nil = true by default)
+	AllowFallbacks *bool      `json:"-"` // Optional: Controls fallback behavior (nil = true by default)
 }
 
 // ErrorField represents detailed error information.

core/schemas/mcp.go

@@ -4,7 +4,6 @@ package schemas
 // MCPConfig represents the configuration for MCP integration in Bifrost.
 // It enables tool auto-discovery and execution from local and external MCP servers.
 type MCPConfig struct {
-	ServerPort    *int              `json:"server_port,omitempty"`    // Port for local MCP server (only required for local tool setup, defaults to 8181)
 	ClientConfigs []MCPClientConfig `json:"client_configs,omitempty"` // Per-client execution configurations
 }
 

docs/README.md

@@ -0,0 +1,111 @@
+# Bifrost Documentation
+
+Welcome to Bifrost - the unified AI model gateway that provides seamless integration with multiple AI providers through a single API.
+
+## 🚀 Quick Start
+
+Choose your preferred way to use Bifrost:
+
+| Usage Mode            | Best For                            | Setup Time | Documentation                                           |
+| --------------------- | ----------------------------------- | ---------- | ------------------------------------------------------- |
+| **🔧 Go Package**     | Direct integration, maximum control | 2 minutes  | [📖 Go Package Guide](quickstart/go-package.md)         |
+| **🌐 HTTP Transport** | Language-agnostic, microservices    | 30 seconds | [📖 HTTP Transport Guide](quickstart/http-transport.md) |
+
+**New to Bifrost?** Start with [⚡ Quick Start](quickstart/) to get running in under 30 seconds.
+
+---
+
+## 🎯 I Want To...
+
+| Task                            | Go Here                                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------- |
+| **Get started in 30 seconds**   | [⚡ Quick Start](quickstart/)                                                   |
+| **Replace my OpenAI SDK calls** | [🔄 OpenAI Integration](usage/http-transport/integrations/openai-compatible.md) |
+| **Use Bifrost in my Go app**    | [🔧 Go Package Usage](usage/go-package/)                                        |
+| **Configure via HTTP/JSON**     | [🌐 HTTP Transport Usage](usage/http-transport/)                                |
+| **Add fallback providers**      | [🔄 Providers](usage/providers.md)                                              |
+| **Understand the architecture** | [🏛️ Architecture](architecture/)                                                |
+| **See practical examples**      | [💡 Examples](examples/)                                                        |
+| **Deploy to production**        | [🚀 Production Guide](usage/http-transport/configuration/)                      |
+| **Contribute to the project**   | [🤝 Contributing](contributing/)                                                |
+
+---
+
+## 📚 Documentation Sections
+
+### ⚡ [Quick Start](quickstart/)
+
+Get running in under 30 seconds with step-by-step guides for both Go package and HTTP transport usage.
+
+### 📖 [Usage](usage/)
+
+Complete API reference and usage guides:
+
+- **[🔧 Go Package](usage/go-package/)** - Direct Go integration
+- **[🌐 HTTP Transport](usage/http-transport/)** - REST API with drop-in integrations
+
+### 🏛️ [Architecture](architecture/)
+
+Deep dive into Bifrost's design, performance, and internals:
+
+- System overview and request flow
+- Performance benchmarks and optimization
+- Plugin and MCP architecture
+
+### 💡 [Examples](examples/)
+
+Practical, executable examples for common use cases:
+
+- End-to-end tool calling
+- MCP integration scenarios
+- Production deployment patterns
+
+### 🔧 Core Concepts
+
+Universal concepts that apply to both Go package and HTTP transport:
+
+- **[🔗 Providers](usage/providers.md)** - Multi-provider support and advanced configurations
+- **[🔑 Key Management](usage/key-management.md)** - API key rotation and distribution
+- **[⚡ Memory Management](usage/memory-management.md)** - Performance optimization
+- **[🌐 Networking](usage/networking.md)** - Proxies, timeouts, and retries
+- **[❌ Error Handling](usage/errors.md)** - Error types and troubleshooting
+
+### 🤝 [Contributing](contributing/)
+
+Help improve Bifrost for everyone:
+
+- Development setup and guidelines
+- Adding new providers and plugins
+- Documentation standards
+
+### 📊 Additional Resources
+
+- **[📈 Benchmarks](benchmarks.md)** - Performance metrics and comparisons
+- **[🔍 Troubleshooting](troubleshooting.md)** - Common issues and solutions
+- **[❓ FAQ](faq.md)** - Frequently asked questions
+
+---
+
+## 🌟 What Makes Bifrost Special
+
+- **🔄 Unified API** - One interface for OpenAI, Anthropic, Bedrock, and more
+- **⚡ Intelligent Fallbacks** - Automatic failover between providers and models
+- **🛠️ MCP Integration** - Model Context Protocol for external tools
+- **🔌 Extensible Plugins** - Custom middleware and request processing
+- **🎯 Drop-in Compatibility** - Replace existing provider APIs without code changes
+- **🚀 Production Ready** - Built for scale with comprehensive monitoring
+
+---
+
+## 💡 Quick Links
+
+- **[⚡ 30-Second Setup](quickstart/)** - Get started immediately
+- **[🔄 Migration Guide](usage/http-transport/integrations/migration-guide.md)** - Migrate from existing providers
+- **[📊 Benchmarks](benchmarks.md)** - Performance benchmarks and optimization
+- **[🛠️ Production Deployment](usage/http-transport/configuration/)** - Scale to production
+
+---
+
+**Need help?** Check our [❓ FAQ](faq.md) or [🔧 Troubleshooting](troubleshooting.md).
+
+Built with ❤️ by the Maxim

docs/architecture/README.md

@@ -0,0 +1,140 @@
+# 🏗️ Bifrost Architecture
+
+Deep dive into Bifrost's system architecture - designed for **10,000+ RPS** with advanced concurrency management, memory optimization, and extensible plugin architecture.
+
+---
+
+## 📑 Architecture Navigation
+
+### **🎯 Core Architecture**
+
+| Document                                       | Description                                 | Focus Area                               |
+| ---------------------------------------------- | ------------------------------------------- | ---------------------------------------- |
+| **[🌐 System Overview](./system-overview.md)** | High-level architecture & design principles | Components, interactions, data flow      |
+| **[🔄 Request Flow](./request-flow.md)**       | Request processing pipeline deep dive       | Processing stages, memory management     |
+| **[📊 Benchmarks](../benchmarks.md)**          | Performance benchmarks & optimization       | Metrics, scaling, optimization           |
+| **[⚙️ Concurrency](./concurrency.md)**         | Worker pools & threading model              | Goroutines, channels, resource isolation |
+
+### **🔧 Internal Systems**
+
+| Document                                         | Description                         | Focus Area                              |
+| ------------------------------------------------ | ----------------------------------- | --------------------------------------- |
+| **[🔌 Plugin System](./plugins.md)**             | How plugins work internally         | Plugin lifecycle, interfaces, execution |
+| **[🛠️ MCP System](./mcp.md)**                    | Model Context Protocol internals    | Tool discovery, execution, integration  |
+| **[💡 Design Decisions](./design-decisions.md)** | Architecture rationale & trade-offs | Why we built it this way, alternatives  |
+
+---
+
+## 🚀 Quick Start by Role
+
+### **🔧 System Administrators**
+
+1. **[System Overview](./system-overview.md)** - Deployment architecture
+2. **[Benchmarks](../benchmarks.md)** - Scaling and capacity planning
+3. **[Concurrency](./concurrency.md)** - Resource tuning parameters
+
+### **👨‍💻 Backend Developers**
+
+1. **[Request Flow](./request-flow.md)** - Processing pipeline internals
+2. **[Plugin System](./plugins.md)** - Extension mechanisms
+3. **[Design Decisions](./design-decisions.md)** - Implementation rationale
+
+### **🏗️ Platform Engineers**
+
+1. **[Benchmarks](../benchmarks.md)** - Throughput and optimization
+2. **[Concurrency](./concurrency.md)** - Resource allocation strategies
+3. **[System Overview](./system-overview.md)** - Integration architecture
+
+### **🔌 Plugin Developers**
+
+1. **[Plugin System](./plugins.md)** - Internal plugin architecture
+2. **[Request Flow](./request-flow.md)** - Hook points and data flow
+3. **[MCP System](./mcp.md)** - Tool integration patterns
+
+---
+
+## 🏗️ Architecture at a Glance
+
+### **High-Performance Design Principles**
+
+- **🔄 Asynchronous Processing** - Channel-based worker pools eliminate blocking
+- **💾 Memory Pool Management** - Object reuse minimizes garbage collection
+- **🏗️ Provider Isolation** - Independent resources prevent cascade failures
+- **🔌 Plugin-First Architecture** - Extensible without core modifications
+- **⚡ Connection Optimization** - HTTP/2, keep-alive, intelligent pooling
+
+### **System Components Overview**
+
+**Processing Flow:** Transport → Router → Plugins → MCP → Workers → Providers
+
+### **Key Performance Characteristics**
+
+| Metric             | Performance       | Details                            |
+| ------------------ | ----------------- | ---------------------------------- |
+| **🚀 Throughput**  | 10,000+ RPS       | Sustained high-load performance    |
+| **⚡ Latency**     | 11-59μs overhead  | Minimal processing overhead        |
+| **💾 Memory**      | Optimized pooling | Object reuse minimizes GC pressure |
+| **🎯 Reliability** | 100% success rate | Under 5000 RPS sustained load      |
+
+### **Architectural Features**
+
+- **🔄 Provider Isolation** - Independent worker pools prevent cascade failures
+- **💾 Memory Optimization** - Channel, message, and response object pooling
+- **🎣 Extensible Hooks** - Plugin system for custom logic injection
+- **🛠️ MCP Integration** - Native tool discovery and execution system
+- **📊 Built-in Observability** - Prometheus metrics without external dependencies
+
+---
+
+## 📚 Core Concepts
+
+### **Request Lifecycle**
+
+1. **Transport** receives request (HTTP/SDK)
+2. **Router** selects provider and manages load balancing
+3. **Plugin Manager** executes pre-processing hooks
+4. **MCP Manager** discovers and prepares available tools
+5. **Worker Pool** processes request with dedicated provider workers
+6. **Memory Pools** provide reusable objects for efficiency
+7. **Plugin Manager** executes post-processing hooks
+8. **Transport** returns response to client
+
+### **Scaling Strategies**
+
+- **Vertical Scaling** - Increase pool sizes and buffer capacities
+- **Horizontal Scaling** - Deploy multiple instances with load balancing
+- **Provider Scaling** - Independent worker pools per provider
+- **Memory Scaling** - Configurable object pool sizes
+
+### **Extension Points**
+
+- **Plugin Hooks** - Pre/post request processing
+- **Custom Providers** - Add new AI service integrations
+- **MCP Tools** - External tool integration
+- **Transport Layers** - Multiple interface options (HTTP, SDK, gRPC planned)
+
+---
+
+## 🔗 Related Documentation
+
+### **Usage Documentation**
+
+- **[🚀 Quick Start](../quickstart/README.md)** - Get started with Bifrost
+- **[🌐 HTTP Transport](../usage/http-transport/README.md)** - HTTP API usage
+- **[📦 Go Package](../usage/go-package/README.md)** - Go SDK usage
+
+### **Configuration**
+
+- **[🔧 Provider Setup](../usage/http-transport/configuration/providers.md)** - Provider configuration
+- **[🔌 Plugin Setup](../usage/http-transport/configuration/plugins.md)** - Plugin configuration
+- **[🛠️ MCP Setup](../usage/http-transport/configuration/mcp.md)** - MCP configuration
+
+### **Operations**
+
+- **[📊 Monitoring](../usage/monitoring.md)** - Observability and metrics
+- **[🔐 Security](../usage/key-management.md)** - Key management and security
+- **[🌐 Networking](../usage/networking.md)** - Network configuration
+
+---
+
+**💡 New to Bifrost architecture?** Start with **[System Overview](./system-overview.md)** for the complete picture, then dive into **[Request Flow](./request-flow.md)** to understand how it all works together.