Khadem Logo
Khadem BETA

Project Structure

Understand the Khadem project architecture. A clean, organized structure inspired by modern frameworks for scalability and maintainability.

Well-Organized Architecture

Every file and folder has a specific purpose, following Dart package conventions and modern backend best practices for easy navigation and maintenance.

Complete Project Structure

Here's the complete folder structure generated by khadem new:

text
my_api/
├── lib/
│   ├── main.dart               # Application entry point
│   ├── app/
│   │   ├── http/
│   │   ├── jobs/
│   │   ├── listeners/
│   │   ├── observers/
│   │   ├── models/
│   │   └── providers/
│   ├── config/ # Application configuration
│   ├── core/
│   │   └── kernel.dart        # Application kernel
│   ├── database/
│   └── routes/
│       ├── socket.dart
│       └── web.dart
├── config/
├── lang/
│   ├── ar/
│   └── en/
├── public/
├── resources/
├── storage/
├── tests/                      # Test files
├── .env                        # Environment variables
├── .gitignore                  # Git ignore rules
├── pubspec.yaml                # Package configuration
└── pubspec.lock                # Package lock file

Application Layer

  • lib/app/ — Business logic
  • lib/core/ — Kernel & bootstrap
  • lib/routes/ — Route definitions

Data Layer

  • lib/database/ — Migrations & seeders
  • storage/ — File storage & cache
  • lang/ — Translations

Configuration

  • config/ — Environment settings
  • .env — Environment variables
  • pubspec.yaml — Dependencies

The lib/ Directory

The core of your Dart application following modern package conventions. All source code lives within lib/.

HTTP Layer

Request handling & middleware

  • controllers/

    Route handlers for requests

  • middleware/

    Auth, CORS, logging filters

Domain Layer

Business logic & models

  • models/

    Database entities & relationships

  • providers/

    Service providers & DI

  • jobs/

    Background queue jobs

  • listeners/

    Event listeners

text
lib/app/
├── http/
│   ├── controllers/
│   │   ├── home_controller.dart
│   │   ├── user_controller.dart
│   │   └── api/
│   │       └── v1/
│   │           └── auth_controller.dart
│   └── middleware/
│       ├── auth_middleware.dart
│       ├── cors_middleware.dart
│       └── logging_middleware.dart
├── models/
│   ├── user.dart
│   └── post.dart
├── providers/
│   ├── app_service_provider.dart
│   ├── event_service_provider.dart
│   └── scheduler_service_provider.dart
├── jobs/
│   ├── send_welcome_email_job.dart
│   ├── process_image_job.dart
│   └── email/
│       └── send_notification_job.dart
├── listeners/
│   └── user_registered_listener.dart
├── observers/
│   └── user_registered_observer.dart

Routes Directory

Define all application routes organized by protocol type.

web.dart

HTTP routes for REST API endpoints

socket.dart

WebSocket routes for real-time communication

dart
// lib/routes/web.dart
import 'package:khadem/khadem_dart.dart';
import '../app/http/controllers/home_controller.dart';
import '../core/kernel.dart';

// Route registration receives a ServerRouter. Global middleware should be applied on the Server instance (see main.dart).
void registerRoutes(ServerRouter router) {
    // API Routes
    router.group(
        prefix: '/api',
        middleware: [],
        routes: (r) {
            r.get('/hello', HomeController.index);
            r.get('/welcome', HomeController.welcome);
            r.get('/stream', HomeController.stream);
        },
    );
}

// routes/socket.dart
import 'package:khadem/khadem_dart.dart';

void registerSocketRoutes(SocketServer socketServer) {
    socketServer.on('chat:message', (socket, data) {
        // Handle chat messages
    });

    socketServer.on('user:join', (socket, data) {
        // Handle user joining
        socket.broadcast('user:joined', data);
    });
}

Key Directories

lib/core/

Application kernel handling bootstrapping, service registration, and framework setup.

Key file: kernel.dart

lib/database/

Database migrations and seeders for schema management.

  • • migrations/ — Schema changes
  • • seeders/ — Test data

storage/

File storage system for application files, cache, and logs.

  • • app/ — App files
  • • cache/ — Cache data
  • • logs/ — Log files

lang/

Localization files for multi-language support.

  • • ar/ — Arabic translations
  • • en/ — English translations

public/

Publicly accessible static files served directly.

  • • assets/ — CSS, JS, images

resources/

Application resources and view templates.

  • • views/ — Template files

Entry Points

lib/main.dart

Main application entry point for bootstrapping and server startup.

bin/

CLI entry points and command-line scripts.

Best Practices

Do's

  • Keep controllers thin, delegate to services
  • Use meaningful names for files and directories
  • Group related functionality together
  • Follow single responsibility principle

Don'ts

  • Put business logic in controllers
  • Create deep directory nesting
  • Mix different concerns in one file
  • Hardcode configuration values

Customizing the Structure

While Khadem provides a solid foundation, you can customize it to fit your needs.

Important

When customizing, update imports and service registrations in lib/core/kernel.dart.

Example: Adding Custom Directories

text
my_api/
├── lib/
│   ├── app/
│   │   ├── http/
│   │   ├── services/
│   │   │   ├── payment/
│   │   │   │   ├── stripe_service.dart
│   │   │   │   └── paypal_service.dart
│   │   │   └── notification/
│   │   │       ├── email_service.dart
│   │   │       └── sms_service.dart
│   │   └── repositories/
│   │       ├── user_repository.dart
│   │       └── post_repository.dart
│   ├── core/
│   └── database/
├── config/
│   ├── payment.dart
│   └── notification.dart
└── tests/
    ├── unit/
    │   ├── services/
    │   └── repositories/
    └── feature/
        ├── payment/
        └── notification/

Questions about Structure?

Join our community to discuss project organization and best practices.

Join Discussion

On this page