Skip to main content

Project Structure

Understanding the default project structure in Vaden is key to maintaining clean and scalable applications. Below is an overview of how a typical Vaden project is organized.

my_vaden_project/
├── bin/
│   └── server.dart               # Entry point for your server (main file)
├── lib/
│   ├── config/                    # Application configuration files (e.g., OpenAPI, settings)
│   ├── src/                      # Your actual application code (controllers, services, etc)
│   └── vaden_application.dart    # Generated file by vaden_class_scanner
├── application.yaml              # Vaden configuration
├── pubspec.yaml                  # Project dependency manager
└── build.yaml                    # build_runner configuration

bin/server.dart​

This is the main entry point of your application. It loads the generated vaden_application.dart and starts the HTTP server:

import 'package:my_vaden_project/vaden_application.dart';
import 'package:shelf/shelf_io.dart';

void main() async {
  final app = await createApplication();
  await serve(app.handler, 'localhost', 8080);
}

lib/vaden_application.dart​

This file is generated automatically by the vaden_class_scanner. It scans all annotations (@Controller, @Service, @Bean, etc.) and composes the full application instance with routing, DI, and middleware configuration. You should not edit this file manually.

lib/config/​

This folder contains configuration files and classes. For example:

  • openapi.dart – declares OpenAPI structure.
  • app_config.dart – provides beans using @Configuration() and @Bean().
  • settings.dart – loads and represents application settings from YAML.

lib/src/​

This is where your actual business logic lives. It’s where you define:

  • controllers/ – route handlers using @Controller.
  • services/ – injectable services using @Service.
  • repositories/ – persistence logic using @Repository.
  • dtos/ – data structures and DTOs using @DTO.
  • middlewares/ – request interceptors using Middleware.
  • guards/ – authorization checks using Guard.

You are free to organize this folder in any way that fits your architecture.

application.yaml​

This optional file can be placed at the root of your project and is used to configure global settings for Vaden. It works similarly to .env files in other frameworks, but with YAML syntax.

Typical usage includes:

  • Declaring the server port and host
  • Defining storage provider (local, s3, firebase)
  • Configuring database access
  • Providing OpenAPI metadata

Example:

server:
  port: 8080
  host: localhost

database:
  provider: postgres
  postgres:
    host: localhost
    port: 5432
    database: my_app
    username: user
    password: pass

openapi:
  title: My API
  version: 1.0.0
  description: Auto-generated by Vaden

The values in application.yaml are automatically loaded into ApplicationSettings, which can be injected using @Bean() for configuration-based services.