Module Architecture

Last Updated: May 11, 2025

The Typus Development Framework is built around a modular architecture that promotes separation of concerns, reusability, and maintainability. This document explains the module system design patterns and how they are implemented throughout the framework.

Module System Overview

Module Structure

Each module in the Typus Development Framework follows a consistent structure:

module/
├── ModuleClass.ts        # Main module class
├── index.ts              # Module exports
├── constants.ts          # Module-specific constants
├── controllers/          # API controllers
│   └── ModuleController.ts
├── services/             # Business logic services
│   └── ModuleService.ts
├── validation/           # Input validation schemas
│   └── moduleSchemas.ts
└── README.md             # Module documentation

Additional directories may be present depending on the module's functionality:

• strategies/ - Authentication strategies (Auth module)
• providers/ - Service providers (Email module)
• repositories/ - Data access repositories (when needed)
• templates/ - Email or other templates
• assets/ - Static assets

Module Class

Each module is defined by a class that extends BaseModule. This class is responsible for:

• Defining the module's name and metadata
• Registering controllers, services, and other components
• Handling module initialization and setup

Module Registration

Modules are typically registered in a central configuration file (e.g., modules.config.ts) and loaded by the application during startup.

Module Components

Controllers

Controllers are responsible for handling HTTP requests, defining API endpoints, and delegating to services. They extend BaseController.

Key responsibilities:

• Route definition
• Request validation
• Service delegation
• Response formatting

Services

Services encapsulate the business logic of a module and interact with data sources (e.g., databases via Prisma). They extend BaseService.

Key responsibilities:

• Business logic implementation
• Data access orchestration
• Transaction management
• Third-party integrations

Validation

Input validation for API endpoints is handled using schema-based validation libraries like Joi. Schemas define the expected structure and types of request data.

Key features:

• Type validation
• Required fields
• Custom validation rules
• Error messages

Frontend Module Structure

Frontend modules follow a similar pattern:

frontend/src/modules/moduleName/
├── components/           # Module-specific components
│   └── ModuleComponent.vue
├── pages/                # Page components
│   └── index.vue
├── composables/          # Composable functions
│   └── useModuleFeature.ts
├── config.dsx/           # DSX configuration
│   └── module.dsx.ts
└── module.menu.ts        # Module menu configuration

Core Modules

The framework includes several core modules:

Auth Module

Handles authentication, authorization, and user management:

• User registration and login
• Password management
• Two-factor authentication
• OAuth integration
• Role-based access control

Email Module

Manages email communication:

• Email templates
• Multiple provider support (SendGrid, AWS SES, etc.)
• Queue-based sending
• Template rendering

FileSystem Module

Handles file operations:

• File uploads and storage
• File validation
• Directory management
• Access control

Notification Module

Manages system notifications:

• In-app notifications
• Email notifications
• Telegram integration
• Notification templates

Custom Modules

Developers can create custom modules for specific application needs:

Blog Module

Manages blog content:

• Posts and categories
• Content management
• SEO optimization
• Comments (optional)

Shop Module

E-commerce functionality:

• Products and categories
• Order processing
• Inventory management
• Payment integration (planned)

Module Communication

Modules can communicate with each other through several mechanisms:

1. Direct Service Injection

Services from one module can be injected into another, typically via constructor injection if they are registered in the DI container.

2. Event-Based Communication

Modules can emit and listen to events using a shared event bus, allowing for decoupled communication.

3. Context System

The global context or DI container can be used to retrieve instances of services registered by other modules.

Module Configuration

Modules are typically configured using environment variables or dedicated configuration files, allowing for flexibility across different environments.

Benefits of Modular Architecture

1. Separation of Concerns: Each module handles a specific aspect of the application
2. Reusability: Modules can be reused across different projects
3. Maintainability: Changes to one module don't affect others
4. Testability: Modules can be tested in isolation
5. Scalability: New features can be added as new modules
6. Team Collaboration: Different teams can work on different modules
7. Flexibility: Modules can be enabled/disabled as needed

Best Practices

1. Single Responsibility: Each module should have a clear, focused purpose
2. Encapsulation: Keep module internals private, expose only necessary interfaces
3. Minimal Dependencies: Minimize dependencies between modules
4. Consistent Structure: Follow the established module structure
5. Documentation: Each module should include documentation
6. Testing: Write tests for each module's functionality
7. Configuration: Make modules configurable through environment variables