Backend Architecture Overview

Last Updated: May 19, 2025

This document provides an overview of the backend architecture of the Typus Development Framework, describing its structure, key components, and design principles.

Architecture Principles

The backend architecture of the Typus Development Framework is built on several key principles:

1. Modularity: The system is divided into independent modules that can be developed, tested, and deployed separately.
2. Dependency Injection: Components are loosely coupled through a dependency injection container.
3. Domain-Driven Design: The architecture follows DDD principles, with clear separation of domain logic.
4. Type Safety: TypeScript is used throughout the codebase to ensure type safety.
5. Extensibility: The architecture is designed to be easily extended with new modules and features.
6. Testability: Components are designed to be easily testable in isolation.

High-Level Architecture

The backend is built as a modular Express.js application with TypeScript, organized into several layers:

Directory Structure

The backend codebase is organized into the following main directories:

backend/
├── src/
│   ├── config/         # Application configuration
│   ├── constants/      # Application constants
│   ├── core/           # Core framework components
│   ├── dsl/            # Domain Specific Language system
│   ├── dynamic-router/ # Dynamic routing system
│   ├── modules/        # Application modules
│   ├── types/          # TypeScript type definitions
│   └── utils/          # Utility functions
├── server.ts           # Application entry point
└── tsconfig.json       # TypeScript configuration

Core Framework

The core framework provides the foundation for the application, including base classes, utilities, and infrastructure components.

Key Core Components

Application

The Application component is responsible for bootstrapping and running the application:

• Application.ts: Main application class that initializes and configures the Express app
• AppConfig.ts: Application configuration interface

Base Classes

Base classes provide common functionality for application components:

• BaseController.ts: Base class for API controllers
• BaseService.ts: Base class for services
• BaseRepository.ts: Base class for repositories
• BaseModule.ts: Base class for application modules
• BaseError.ts: Base class for application errors
• BaseQueue.ts: Base class for queue workers

Dependency Container

The dependency container manages component instantiation and dependency injection:

• Container.ts: Dependency injection container
• registry.ts: Component registry
• types.ts: Type definitions for the container

Context

The context system provides request-scoped data and services:

• Context.ts: Request context class
• ContextManager.ts: Context lifecycle management
• ContextMiddleware.ts: Middleware for context initialization

Database

Database integration components:

• prisma.ts: Prisma ORM client and utilities

Logger

Logging system components:

• Logger.ts: Main logger class
• LoggerConfig.ts: Logger configuration
• transports/: Logger transport implementations

Middleware

Middleware components for request processing:

• BaseMiddleware.ts: Base middleware class
• ErrorHandlerMiddleware.ts: Global error handler
• LoggingMiddleware.ts: Request logging
• ValidationMiddleware.ts: Request validation
• MiddlewareConfigurator.ts: Middleware configuration

Queue

Asynchronous task processing components:

• BaseQueue.ts: Base queue class
• QueueManager.ts: Queue management
• QueueWorker.ts: Worker implementation

Routing

Routing components:

• Router.ts: Router implementation
• RouterHelper.ts: Routing utilities

Security

Security components:

• SecurityConfig.ts: Security configuration
• abilities/: Permission management

Module System

The application is organized into modules, each responsible for a specific domain or feature:

Module Structure

Each module follows a consistent structure:

modules/example/
├── ExampleModule.ts       # Module definition
├── index.ts               # Module exports
├── controllers/           # API controllers
│   └── ExampleController.ts
├── services/              # Business logic
│   └── ExampleService.ts
├── repositories/          # Data access (optional)
│   └── ExampleRepository.ts
├── validation/            # Request validation (optional)
│   └── exampleSchemas.ts
└── dsl/                   # DSL models (optional)
    └── example.model.ts

Key Modules

Auth Module

Authentication and authorization:

• User authentication (local, OAuth)
• Token management (JWT)
• Session handling

User Module

User management:

• User registration
• Profile management
• User preferences

CMS Module

Content management:

• Content creation and editing
• Content publishing
• Content templates

Email Module

Email functionality:

• Email templates
• Email sending
• Email providers integration

FileSystem Module

File management:

• File upload and storage
• File retrieval
• File metadata

Notification Module

Notification system:

• Notification creation
• Notification delivery
• Notification channels (email, in-app)

DSL System

The Domain Specific Language (DSL) system provides a way to define data models and generate TypeScript interfaces and Prisma schema:

DSL Components

• DslModule.ts: DSL module definition
• registry-adapter.ts: Adapter for the shared DSL registry
• controllers/DslController.ts: API controller for DSL operations
• services/DslService.ts: Service for DSL operations
• validation/dslSchemas.ts: Validation schemas for DSL operations

Dynamic Router

The Dynamic Router system provides content-based routing:

Dynamic Router Components

• DynamicRouterModule.ts: Dynamic Router module definition
• controllers/DynamicRouterController.ts: API controller for dynamic routing
• services/DynamicRouterService.ts: Service for dynamic routing
• validation/dynamicRouterSchemas.ts: Validation schemas for dynamic routing

Request Processing Flow

The following diagram illustrates how a typical request is processed by the backend:

Error Handling

The backend implements a comprehensive error handling system:

Error Types

• BaseError: Base class for all application errors
• ValidationError: Input validation errors
• AuthError: Authentication and authorization errors
• NotFoundError: Resource not found errors
• BusinessError: Business logic errors

Configuration System

The backend uses a configuration system that supports different environments:

Configuration Files

• app.config.ts: Application configuration
• db.config.ts: Database configuration
• cors.config.ts: CORS configuration
• env.config.ts: Environment-specific configuration
• modules.config.ts: Module configuration

Dependency Injection

The backend uses a dependency injection container to manage component instantiation and dependencies:

Dependency Injection Features

• Component Registration: Register components with the container
• Lifecycle Management: Manage component lifecycle (singleton, transient, scoped)
• Dependency Resolution: Automatically resolve component dependencies
• Circular Dependency Detection: Detect and prevent circular dependencies

Conclusion

The backend architecture of the Typus Development Framework provides a robust foundation for building scalable, maintainable, and extensible applications. The modular design, combined with dependency injection and clear separation of concerns, allows for easy development and testing of individual components.

The architecture is designed to be flexible and adaptable to different application requirements, while providing a consistent structure and set of patterns for developers to follow. This approach helps ensure that applications built with the framework are maintainable and can evolve over time.