How cambusahq/core works
Major Components
• API Layer: This includes the "api" directory with subdirectories for controllers (handling HTTP requests), models (data definitions and blueprints for automatic CRUD generation), hooks (lifecycle hooks/extensions), middlewares (request processing extensions), and helpers (utility functions).
• Configuration: Represent the "config" directory which centralizes database, routes, middlewares, security, logger, server, and swagger settings.
• Core Library/Framework: Include elements from the "src" directory under "src/lib" which holds core functionalities such as the cambusa global object, datastore management (EntitySubscriber, primaryKeyGenerator, etc.), routing logic (blueprints, validation, websocketHandler), and loader utilities for helpers, hooks, and middlewares.
• Deployment & Environment: Show Docker-related files (Dockerfile, docker-compose.yml) along with environment and linting configurations (e.g., .editorconfig, .prettierrc) which support deployment and development.
Out Relationships and Data Flow
• Global Application Instance ("cambusa" object): This acts as a central hub, providing access to configuration (cambusa.config), the logger (cambusa.log), the database (cambusa.db), models (cambusa.models), and helpers (cambusa.helpers).
• Routing: Show how custom routes defined in "config/routes.js" as well as auto-generated CRUD routes (blueprints) from models are passed to controllers found under "api/controllers".
• Business Logic and Middleware Chain: Indicate that incoming requests travel through a middleware pipeline (configured via "config/middlewares.js" and implemented in "api/middlewares") before reaching controllers that may use models and helpers.
• Persistence: Represent the database connection configured in "config/database.js" and the ORM integration (TypeORM) as part of the datastore logic in the "src/lib/datastore" directory.
• WebSocket and Real-Time Support: Include the separate pathway managed by the websocketHandler (under "src/lib/router/websocketHandler.js") for real-time connections.
Architectural Patterns and Design Principles
• MVC/Blueprint Pattern: Emphasize the resemblance to Sails.js. Models, controllers, and blueprints are used to generate standard CRUD operations automatically.
• Modular and Extensible Design: The separation of concerns with clearly defined directories for controllers, models, middleware, hooks, and helpers shows an extensible design where components can be individually maintained or replaced.
• Global Service Locator: The "cambusa" global object plays a central role for dependency access (configuration, logging, ORM, model management, etc.).
• Configurability: The extensive "config" directory facilitates environment-specific or centralized settings (security, routes, logger, etc.).
Relevant Technologies, Frameworks, and Libraries
• Bun as the runtime and bundler.
• Elysia (used internally in some components for middleware/plugins, e.g., in cors.js).
• TypeORM for database operations.
• Pino for logging.
• Docker for containerization.
• WebSocket integration for real-time communication.
• ESLint, Prettier, and other tooling for coding standards.
Essential Elements
• Component labels (e.g., “API Controllers”, “Middlewares”, “Database Models”, “Core Routers”).
• A section for deployment elements (Docker, environment configuration).