| # Architecture Design | |
| ## Overview | |
| Vortex is built using a **Feature-Based Plugin Architecture** with **Vertical Slices**. This design ensures that each platform integration (LeetCode, Codeforces, etc.) is self-contained, highly modular, and easy to maintain. | |
| ## Modular Structure | |
| Each platform and the AI interface is implemented as a Fastify plugin located in `src/modules/{module_name}/`. This allows for: | |
| - **Isolation**: Changes in one platform don't affect others. | |
| - **Scalability**: Easy to add or remove platforms. | |
| - **Consistency**: Every module follows the same structure and design patterns. | |
| - **AI Integration**: Dedicated MCP module for real-time tool access for AI agents. | |
| ## Vertical Slices | |
| Unlike traditional horizontal layering (where all controllers are in one folder, all services in another), we use vertical slices. All code related to a specific feature (like LeetCode) lives in one directory. | |
| ### Layered Responsibilities | |
| Inside each module, we follow a strict layering pattern: | |
| 1. **Plugin Entry (`index.ts`)**: Exports the Fastify plugin. | |
| 2. **Routes (`routes.ts`)**: Defines endpoints, registers schemas, and assigns handlers. | |
| 3. **Handlers (`handlers/`)**: Extracts data from requests (params, query, body), calls services, and sends responses. | |
| 4. **Services (`services/`)**: Orchestrates business logic. Pure TypeScript, no Fastify dependencies. | |
| 5. **Provider (`provider.ts`)**: Handles external communication (HTTP, GraphQL, Scraping). | |
| 6. **Schemas (`schemas.ts`)**: JSON schemas for request/response validation (also used for Swagger). | |
| 7. **Types (`types.ts`)**: TypeScript interfaces for data structures. | |
| ### MCP Module Structure | |
| The `src/modules/mcp/` module follows a slightly different structure to support the Model Context Protocol: | |
| - **`tools/`**: Implementation of AI-callable tools. | |
| - **`prompts/`**: Pre-defined prompts for LLM guidance. | |
| - **`resources/`**: Static or dynamic data resources exposed to agents. | |
| - **`index.ts`**: Plugin registration using `fastify-mcp`. | |
| ## Data Flow | |
| ```mermaid | |
| graph TD | |
| User([User]) -->|HTTP Request| Server[Fastify Server] | |
| Server -->|Routes| Handler[Handler Layer] | |
| Handler -->|Params/Query| Service[Service Layer] | |
| Service -->|Business Logic| Provider[Provider Layer] | |
| Provider -->|Fetch| ExternalAPI[(External API / Web)] | |
| ExternalAPI -->|Data| Provider | |
| Provider -->|Raw Data| Service | |
| Service -->|Model/Format| Handler | |
| Handler -->|JSON Response| User | |
| ``` | |
| ## Shared Infrastructure | |
| - **`src/shared/`**: Common utilities, midlewares, and HTTP clients used across modules. | |
| - **`src/config/`**: Environment variable management using `fastify-env`. | |
| - **`src/types/`**: Global type definitions and Fastify type augmentation. | |
| ## Performance & Validation | |
| - **JSON Schema**: Every route uses high-performance JSON schema validation. | |
| - **Serialization**: Fastify uses `fast-json-stringify` for lightning-fast responses based on our schemas. | |
| - **TypeScript**: Full end-to-end type safety from provider to handler. | |