How emi-arcioni/cocos-backend-challenge works
Main Components
• NestJS Application: Represented by the main entry point (src/main.ts) and the NestJS modules.
• Modules (each as separate components):
• Orders Module: Handles order creation, cancellation, and order validation. Contains controllers, services, DTOs, entities, and repositories.
• Portfolios Module: Manages portfolio recalculations, positions, and balances.
• Instruments Module: Handles retrieval and validation of financial instruments.
• Market Data Module: Provides market data entities and services for real-time or stored market information.
• Users Module: Manages user-related operations, such as validations (e.g., user existence) and user repository management.
• Common Module: Contains shared configurations (e.g., database config), enums, migrations, and scripts for synchronization and migrations.
• External Dependencies:
• PostgreSQL: The primary database system that holds orders, portfolios, instruments, and user data.
• Docker Compose: Optional service for running the Postgres database.
Relationships and Interactions
• API Flow:
• Incoming REST API requests (e.g., placing orders, retrieving portfolios, fetching instruments) are routed via controllers.
• Controllers delegate to their corresponding services, which contain business logic (for example, order validation including balance calculations and applying pessimistic locking via query runner transactions).
• Services interact with repository components to perform CRUD operations on the PostgreSQL database.
• Data Flow:
• Bidirectional communication where appropriate, such as controllers receiving processed data back from services.
• Migration and Synchronization:
• “scripts” component where database migrations and portfolio synchronization occurs, as part of the development and deployment process.
Architectural Patterns and Design Principles
• Module-Based Architecture: Each main entity (orders, portfolios, instruments, market data, users) is encapsulated in its own module, promoting separation of concerns and maintainability.
• MVC-like Flow: Controllers handle the HTTP layer, services implement business logic, and repositories interact with the database.
• Transaction Management & Locking: Emphasize the pessimistic locking strategy used in the orders service to prevent race conditions during order creation.
• Configuration & Shared Utilities: The “common” directory centralizes database configuration, enums, and migration scripts.
• Code Quality & Testing: Note the presence of ESLint/Prettier configurations and separate directories for unit and end-to-end tests.
• API Client: Represent external clients (or Postman) interacting with the system.
• NestJS App: A container for the application that includes:
• Orders Module (with its controller, service, DTOs, entities, and repository)
• Portfolios Module (with its controller, service, and repository)
• Instruments Module (with its controller, service, validations, DTOs, entities, etc.)
• Market Data Module (with its service and repository)
• Users Module (with its controller, service, validations, and repository)
• Common Configurations & Shared Scripts/Migrations
• PostgreSQL Database: Represent as a separate component that the repository layer interacts with.
• Docker Compose (optional) for database provisioning.
• Use another for business logic (services) and controllers.
• Differentiate repositories and external systems (like the database) with separate visual markers.