refactor(core): restructure project architecture

[Xunzhuo]

---

PR Description

What type of PR is this?

refactor(core): restructure project architecture and consolidate test files

What this PR does / why we need it:

This PR performs a major refactoring of the project's core architecture to improve code organization, maintainability, and clarity. The key changes include:

Configuration Reorganization

• Restructured config/ directory with clear categorization:
  • intelligent-routing/ - routing configurations (in-tree and out-tree)
  • semantic-cache/ - caching configurations
  • observability/ - tracing and monitoring configs
  • prompt-guard/ - security domain configurations
  • testing/ - test-specific configurations
  • integration/ - integration-specific configs with dedicated READMEs
• Removed redundant recipe configurations (RECIPES.md, config.recipe-*.yaml)
• Removed environment-specific configs (config.development.yaml, config.production.yaml)

API Server Refactoring

• Split monolithic pkg/api/server.go (1604 lines) into modular route handlers:
  • route_classify.go - classification endpoints
  • route_embeddings.go - embedding endpoints
  • route_model_info.go - model information endpoints
  • route_models.go - model listing endpoints
  • route_system_prompt.go - system prompt endpoints
  • route_api_doc.go - API documentation endpoints
• Improved code maintainability and readability

Package Structure Improvements

• Moved pkg/utils/classification/ → pkg/classification/ (promoted to top-level package)
• Moved pkg/connectivity/mcp/ → pkg/mcp/ (simplified path)
• Reorganized observability packages:
  • pkg/metrics/ → pkg/observability/metrics/
  • pkg/observability/tracing/ (consolidated tracing logic)
  • Added pkg/observability/logging/ (new logging abstraction)

Test Consolidation

• Consolidated 3,000+ lines of scattered cache tests into single cache_test.go
• Consolidated 3,500+ lines of classification tests into single classifier_test.go
• Consolidated 4,500+ lines of extproc tests into single stream_handling_test.go
• Removed redundant benchmark and integration test files
• Improved test organization and reduced duplication

Documentation Updates

• Updated example references (server.py → server_keyword.py)
• Updated configuration path references throughout documentation
• Added integration-specific READMEs for better onboarding

Impact

• 118 files changed: 14,854 insertions(+), 15,840 deletions(-)
• Net reduction of ~1,000 lines while improving organization
• No functional changes - purely structural improvements
• Better separation of concerns and clearer module boundaries

This refactoring sets a solid foundation for future development by making the codebase more navigable and maintainable.

[netlify]

✅ Deploy Preview for vllm-semantic-router ready!

Name	Link
🔨 Latest commit	842bbc5
🔍 Latest deploy log	https://app.netlify.com/projects/vllm-semantic-router/deploys/69077177fb6ae50008f996d1
😎 Deploy Preview	https://deploy-preview-571--vllm-semantic-router.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[github-actions]

👥 vLLM Semantic Team Notification

The following members have been identified for the changed files in this PR and have been automatically assigned:

📁 config

Owners: @rootfs, @Xunzhuo
Files changed:

• config/integration/aibrix/README.md
• config/integration/dynamo/README.md
• config/integration/kserve/README.md
• config/integration/llm-d/README.md
• config/integration/production-stack/README.md
• config/intelligent-routing/in-tree/bert_classification.yaml
• config/intelligent-routing/in-tree/keyword.yaml
• config/OWNER
• config/intelligent-routing/in-tree/generic_categories.yaml
• config/intelligent-routing/out-tree/config-mcp-classifier.yaml
• config/observability/config.tracing.yaml
• config/prompt-guard/jailbreak_domain.yaml
• config/prompt-guard/pii_domain.yaml
• config/semantic-cache/config.hybrid.yaml
• config/semantic-cache/milvus.yaml
• config/testing/config.e2e.yaml
• config/testing/config.testing.yaml

📁 src

Owners: @rootfs, @Xunzhuo, @wangchen615
Files changed:

• src/semantic-router/pkg/apiserver/config.go
• src/semantic-router/pkg/apiserver/route_api_doc.go
• src/semantic-router/pkg/apiserver/route_classify.go
• src/semantic-router/pkg/apiserver/route_embeddings.go
• src/semantic-router/pkg/apiserver/route_model_info.go
• src/semantic-router/pkg/apiserver/route_models.go
• src/semantic-router/pkg/apiserver/route_not_implemented.go
• src/semantic-router/pkg/apiserver/route_system_prompt.go
• src/semantic-router/pkg/apiserver/server.go
• src/semantic-router/pkg/classification/classifier_test.go
• src/semantic-router/cmd/main.go
• src/semantic-router/go.mod
• src/semantic-router/pkg/cache/cache_factory.go
• src/semantic-router/pkg/cache/cache_test.go
• src/semantic-router/pkg/cache/hybrid_cache.go
• src/semantic-router/pkg/cache/inmemory_cache.go
• src/semantic-router/pkg/cache/milvus_cache.go
• src/semantic-router/pkg/cache/simd_distance_amd64.go
• src/semantic-router/pkg/cache/simd_distance_generic.go
• src/semantic-router/pkg/config/config_test.go
• src/semantic-router/pkg/extproc/extproc_test.go
• src/semantic-router/pkg/extproc/model_selector.go
• src/semantic-router/pkg/extproc/processor.go
• src/semantic-router/pkg/extproc/reason_mode_selector.go
• src/semantic-router/pkg/extproc/request_handler.go
• src/semantic-router/pkg/extproc/response_handler.go
• src/semantic-router/pkg/extproc/router.go
• src/semantic-router/pkg/extproc/server.go
• src/semantic-router/pkg/extproc/utils.go
• src/semantic-router/pkg/services/classification.go
• src/semantic-router/pkg/services/classification_test.go
• src/semantic-router/pkg/tools/tools.go
• src/semantic-router/pkg/utils/http/response.go
• src/semantic-router/pkg/utils/pii/policy.go
• src/semantic-router/pkg/apiserver/server_test.go
• src/semantic-router/pkg/classification/classifier.go
• src/semantic-router/pkg/classification/keyword_classifier.go
• src/semantic-router/pkg/classification/mapping.go
• src/semantic-router/pkg/classification/mcp_classifier.go
• src/semantic-router/pkg/classification/model_discovery.go
• src/semantic-router/pkg/classification/unified_classifier.go
• src/semantic-router/pkg/config/api.go
• src/semantic-router/pkg/mcp/api/types.go
• src/semantic-router/pkg/mcp/factory.go
• src/semantic-router/pkg/mcp/http_client.go
• src/semantic-router/pkg/mcp/interface.go
• src/semantic-router/pkg/mcp/stdio_client.go
• src/semantic-router/pkg/mcp/types.go
• src/semantic-router/pkg/observability/logging/logging.go
• src/semantic-router/pkg/observability/metrics/metrics.go
• src/semantic-router/pkg/observability/metrics/metrics_test.go
• src/semantic-router/pkg/observability/tracing/propagation.go
• src/semantic-router/pkg/observability/tracing/tracing.go
• src/semantic-router/pkg/observability/tracing/tracing_test.go

📁 Root Directory

Owners: @rootfs, @Xunzhuo
Files changed:

• examples/mcp-classifier-server/README.md
• examples/mcp-classifier-server/server_keyword.py.py

📁 tools

Owners: @yuluo-yx, @rootfs, @Xunzhuo
Files changed:

• tools/linter/go/.golangci.yml
• tools/make/build-run-test.mk
• tools/make/common.mk

📁 website

Owners: @Xunzhuo, @rootfs, @yuluo-yx
Files changed:

• website/docs/installation/docker-compose.md
• website/docs/tutorials/mcp-classification/overview.md
• website/docs/tutorials/mcp-classification/protocol.md
• website/docs/tutorials/semantic-cache/milvus-cache.md

---

🎉 Thanks for your contributions!

This comment was automatically generated based on the OWNER files in the repository.

[Xunzhuo]

Follow up, API refactoring.