Vaden Framework

Vaden is a backend framework for Dart inspired by Spring Boot. It is designed to provide a fast and expressive server-side experience by implementing modern backend patterns such as:

• Annotation-based controllers: For defining API endpoints.
• Dependency Injection: For managing service lifecycles and components.
• Middlewares and Guards: For intercepting requests and securing routes.
• DTOs (Data Transfer Objects): For structured data handling.
• OpenAPI documentation: For automated API specification.

Vaden is a backend framework for Dart inspired by Spring Boot. It is designed to provide a fast and expressive server-side experience by bringing modern backend concepts to the Dart ecosystem. Key features include:

• Annotation-based controllers for defining routes and logic.
• Dependency Injection for managing component lifecycles.
• Middlewares and Guards for request processing and security.
• DTOs (Data Transfer Objects) for structured data handling.
• OpenAPI documentation for automated API specifications.

The vaden_mcp server allows AI assistants and LLMs to interact with Vaden backend projects via the Model Context Protocol (MCP). It provides tools for:

• Project Introspection: Scanning and analyzing the project structure.
• Code Generation: Creating controllers, services, and configurations.
• Code Mutation: Adding routes and modifying existing components.
• Context Building: Preparing detailed context specifically for AI-driven code generation.

A VadenModule is a class annotated with @VadenModule that serves as the fundamental organizational unit of a Vaden application. Inspired by NestJS and Angular, modules group related components—such as services, controllers, repositories, and other modules—into cohesive blocks of functionality.

Modules enable:

• Structured Organization: Clearer application architecture.
• Dependency Management: Effective use of Vaden's dependency injection (DI) system.
• Code Reusability: Sharing modules (e.g., a DomainModule) across different parts of an application or between different projects (like backend and frontend).

Vaden provides automatic serialization and deserialization for the following types without requiring custom parsers:

• DateTime: ISO 8601 strings.
• Enums: The enum name (e.g., UserType.admin $\rightarrow$ "admin").
• Duration: Milliseconds.
• Uri: String representation.

@DTO()
class Event {
  final String name;
  final DateTime startTime;     // Automatic ISO 8601
  final Duration duration;      // Automatic milliseconds
  final EventType type;         // Automatic enum name
  final Uri? website;           // Automatic string

  const Event(this.name, this.startTime, this.duration, this.type, this.website);
}

enum EventType { conference, workshop, meetup }

The path parameter in RequestMatcher supports Glob patterns.

Examples:

• /api/** matches everything under /api/
• /users/*.json matches all .json files in /users/

Use the @DTO() annotation to define Data Transfer Objects. These classes are used for the automatic serialization and deserialization of data in API requests and responses.

Requirement: All return types in an @ApiClient() and all parameters marked with @Body() must be annotated with @DTO().

A @Controller('/path') defines a class that handles a group of HTTP routes. The path provided to the decorator acts as a prefix for all methods within that class, allowing you to organize your application modularly.

Constructor injection is supported: if a service is registered in the framework, it can be automatically injected into the controller's constructor.

@Controller('/users')
class UserController {
  @Get('/all')
  String getAll() => 'Listing all users';
}
// Maps to /users/all

Vaden uses several annotations to manage the dependency injection lifecycle:

• @Configuration(): Defines configuration classes that provide object instances.
• @Bean(): Marks a method within a @Configuration() class that provides a specific instance to the injector.
• @Service(): Marks classes as services (prefer registering via interfaces).
• @Repository(): Marks classes as repositories (prefer registering via interfaces).
• @Component(): Marks any class that needs to be registered in the dependency injection system.

By default, all registered classes in Vaden are singletons, meaning the same instance is reused throughout the entire application.

Dependency injection is supported in the following contexts:

• Controllers
• Services
• Repositories
• Middlewares
• Guards
• Beans (via @Bean() methods)