langaro-api 1.2.3 → 1.2.5

package/bin/langaro-api.js

@@ -117,8 +117,15 @@ function runWatch() {
 async function runInit() {
   const ok = await confirm('\n\x1b[33mThis will create project files in the current directory.\x1b[0m Are you sure?\n');
   if (!ok) { console.log('\nAborted.\n'); process.exit(0); }
-  const init = require('../lib/cli/init');
-  await init();
+  const { run } = require('../lib/cli/init');
+  await run();
+}
+
+function runUpdateDocs() {
+  const { updateDocumentation } = require('../lib/cli/init');
+  const root = process.cwd();
+  updateDocumentation(root);
+  console.log('\n  \x1b[32m✔\x1b[0m documentation/ updated successfully.\n');
 }
 
 async function runMigrate() {
@@ -143,6 +150,7 @@ async function main() {
   if (command === 'init') return runInit();
   if (command === 'migrate') return runMigrate();
   if (command === 'new') return runNew();
+  if (command === 'update-docs') { runUpdateDocs(); return process.exit(0); }
   if (command === '--watch') return runWatch();
   if (command === 'generate' || command === 'types') {
     runGenerateTypes();
@@ -163,6 +171,7 @@ async function main() {
     { label: 'New resource', value: 'new', desc: 'Scaffold a new controller, service, model, or route' },
     { label: 'Migrate project', value: 'migrate', desc: 'Replace index.js files with langaro-api loaders' },
     { label: 'Init new project', value: 'init', desc: 'Scaffold a full project from scratch' },
+    { label: 'Update docs', value: 'update-docs', desc: 'Overwrite documentation/ with latest version' },
   ]);
 
   console.log('');
@@ -171,6 +180,7 @@ async function main() {
   if (choice === 'new') return runNew();
   if (choice === 'migrate') return runMigrate();
   if (choice === 'init') return runInit();
+  if (choice === 'update-docs') { runUpdateDocs(); process.exit(0); }
 
   return undefined;
 }

package/lib/cli/documentation-templates/01-architecture-overview.md

@@ -0,0 +1,240 @@
+# Architecture Overview
+
+## Three-Layer Stack
+
+This project is built on a three-layer architecture:
+
+```
+┌─────────────────────────────────────────────────┐
+│              PROJECT CODE (this repo)           │
+│   Controllers, Services, Models, Routes, Jobs,  │
+│   Tasks, Middlewares, Integrations, Utils       │
+├─────────────────────────────────────────────────┤
+│              LANGARO-API (framework)            │
+│   Loaders, CLI, Type Generation, Scaffolding    │
+├─────────────────────────────────────────────────┤
+│           KNEX-EXTENDED-CRUD (library)          │
+│   CRUD class, Validation, Caching, Relations    │
+├─────────────────────────────────────────────────┤
+│         KNEX + MySQL2 + Redis + BullMQ          │
+└─────────────────────────────────────────────────┘
+```
+
+**knex-extended-crud** provides the `CRUD` class — a database abstraction with built-in validation, caching, pagination, relationships, and batch operations. Every database table in the project gets a CRUD instance.
+
+**langaro-api** provides loaders that auto-discover and instantiate all components from their directories, a CLI for scaffolding projects and resources, and a type generation system for IDE IntelliSense.
+
+**Project code** is where business logic lives. It follows the conventions established by the framework: factory functions, naming conventions, directory structure.
+
+---
+
+## Boot Sequence
+
+When `npm run dev` executes, the following happens in order:
+
+```
+1. server.js
+   ├── Load .env (dotenv)
+   ├── Create Knex instance (database/connection.js)
+   ├── Call getAppInstance(knex) → new App(knex)
+   └── Listen on PORT
+
+2. App.constructor → App.init()
+   ├── Set query parser to 'extended'
+   ├── Apply readiness middleware (blocks requests until boot completes)
+   ├── Apply middlewares (CORS, morgan, bodyParser, multer)
+   └── Call this.routes()
+
+3. App.routes()
+   ├── Create Socket.io server
+   │   └── On connection: join rooms by companyId and userId
+   │
+   ├── loadModels(knex, dir, { redis })
+   │   ├── Query information_schema.tables for all table names
+   │   ├── For each table: load optional {table}.model.js config
+   │   ├── For each table: create class extends CRUD { constructor() { super({knex, table, ...config}) } }
+   │   └── Return { models, tableNames }
+   │
+   ├── loadServices(models, io, dir)
+   │   ├── For each model: load optional {table}.services.js factory
+   │   ├── If factory exists: call factory(model, models, io) → custom class extends model
+   │   ├── If no factory: create class extends model (bare CRUD wrapper)
+   │   ├── Also scan for custom services (no DB table)
+   │   ├── Instantiate all services
+   │   └── Return ServicesMap { PascalCaseServices: instance }
+   │
+   ├── initializeQueues(services, io, bullBoardSetQueues)
+   │   ├── Create Redis connection
+   │   ├── loadJobs(services, dir) → scan src/jobs/ recursively
+   │   ├── Register all job configs in jobConfigs Map
+   │   ├── Scan Redis for existing queues with pending jobs → start workers
+   │   ├── Start inactivity cleanup interval (every 1 min)
+   │   └── Return Queue { add(name, data, options) }
+   │
+   ├── loadControllers(services, Queue, io, dir)
+   │   ├── Scan for {table}.controller.js files (flat or nested in subdirs)
+   │   ├── For each: create ServicesClass with { this.service, this.services, this.Queue, this.io }
+   │   ├── Call factory(ServicesClass) → custom class extends ServicesClass
+   │   ├── Instantiate controller
+   │   └── Return ControllersMap { PascalCaseController: instance }
+   │
+   ├── attachRouters(express, controllers, services, dir)
+   │   ├── Scan src/routes/ for {table}.router.js files
+   │   ├── Convert snake_case filename to kebab-case URL path
+   │   ├── Call factory(controllers, services) → Express Router
+   │   └── Mount: express.use('/kebab-path', router)
+   │
+   └── loadTasks(services, Queue, dir)  [skipped in test env]
+       ├── Scan src/tasks/ recursively
+       ├── Call factory(services, Queue) → { task, cronTime, isActive, environments }
+       ├── If isActive && NODE_ENV in environments
+       └── Start CronJob (timezone: America/Sao_Paulo)
+
+4. App.handleErrors()
+   ├── Sentry error handler
+   ├── Axios network errors → 422
+   ├── Safe errors (err.safe = true) → err.code + err.data
+   └── Unsafe errors → 500 + Sentry capture
+
+5. App.isReady = true → release queued requests
+```
+
+---
+
+## Inheritance Chain
+
+The core inheritance pattern flows from database to HTTP:
+
+```
+CRUD (knex-extended-crud)
+  │  Provides: get, getWhere, create, batchCreate, updateWhere,
+  │  batchUpdate, deleteWhere, search, count, createTransaction,
+  │  appendItems, validation, caching
+  │
+  ▼
+Model (auto-generated per table by loadModels)
+  │  class extends CRUD { constructor() { super({knex, table, ...modelConfig}) } }
+  │  Configured by: src/database/models/{table}.model.js
+  │
+  ▼
+Service (factory from loadServices)
+  │  module.exports = (model, models, io) => class extends model { ... }
+  │  File: src/database/services/{table}.services.js
+  │  Has access to: all CRUD methods + custom business logic
+  │
+  ▼
+ServicesClass (created by loadControllers)
+  │  class { constructor() { this.service = serviceInstance;
+  │    this.services = allServicesMap; this.Queue = queueAPI; this.io = socketIo; } }
+  │
+  ▼
+Controller (factory from loadControllers)
+  │  module.exports = (ServicesClass) => class extends ServicesClass { ... }
+  │  File: src/controllers/{table}/{table}.controller.js
+  │  Has access to: this.service, this.services, this.Queue, this.io
+```
+
+**Key insight**: Controllers do NOT inherit CRUD methods directly. They access database operations through `this.service.methodName()` or `this.services.OtherServices.methodName()`.
+
+---
+
+## Dependency Injection Pattern
+
+The framework uses **factory functions** instead of traditional DI containers:
+
+```javascript
+// Service factory receives dependencies as arguments
+module.exports = (model, models, io) => class extends model {
+  // model = CRUD class for this table
+  // models = map of all model constructors
+  // io = Socket.io instance
+};
+
+// Controller factory receives dependencies via ServicesClass
+module.exports = (ServicesClass) => class extends ServicesClass {
+  // this.service = service instance for this controller's table
+  // this.services = map of all service instances
+  // this.Queue = { add(name, data, options) }
+  // this.io = Socket.io instance
+};
+
+// Router factory receives controllers and services
+module.exports = (controllers, services) => {
+  // controllers = map of all controller instances
+  // services = map of all service instances (for middleware)
+};
+
+// Job factory receives services
+module.exports = (services) => ({
+  handle: async (data, job, queue, io) => { ... }
+});
+
+// Task factory receives services and Queue
+module.exports = (services, Queue) => ({
+  task: async () => { ... },
+  cronTime: '...',
+  isActive: true
+});
+```
+
+The loaders wire everything together at boot time. No manual dependency resolution needed.
+
+---
+
+## Directory Structure
+
+```
+src/
+├── config/
+│   ├── server.js              # Entry point: dotenv, knex, startServer, graceful shutdown
+│   ├── app.js                 # App class: middleware, routes, error handling
+│   ├── queues.js              # BullMQ queue management
+│   ├── instrument.js          # Sentry initialization
+│   └── tests/                 # Test setup files
+│       ├── global-setup-tests.js
+│       └── setup-tests.js
+├── database/
+│   ├── connection.js          # Knex MySQL2 connection factory
+│   ├── redis-config.js        # Redis connection parameters
+│   ├── redis-cache.js         # RedisCache singleton (get/set/delete)
+│   ├── models/                # Model config files ({table}.model.js)
+│   │   └── index.js           # loadModels loader
+│   ├── services/              # Service files ({table}.services.js)
+│   │   └── index.js           # loadServices loader
+│   └── tests/                 # Database test utilities
+├── controllers/               # Controller files ({table}/{table}.controller.js)
+│   └── index.js               # loadControllers loader
+├── routes/                    # Router files ({table}.router.js)
+│   └── index.js               # attachRouters loader
+├── jobs/                      # Job files ({name}.js, supports subdirectories)
+│   └── index.js               # loadJobs loader
+├── tasks/                     # Task files ({name}.js, supports subdirectories)
+│   └── index.js               # loadTasks loader
+├── middlewares/                # Middleware files ({name}.middleware.js)
+│   └── auth.middleware.js     # Authentication & authorization
+├── integrations/              # External service wrappers
+├── utils/                     # Utility functions
+│   └── index.js               # Re-exports common utilities
+├── static/                    # Static files
+└── temp/                      # Temporary file storage
+```
+
+---
+
+## Naming Conventions Quick Reference
+
+| Component | File Pattern | Key Name | Example |
+|-----------|-------------|----------|---------|
+| Model | `{table}.model.js` | — | `users.model.js` |
+| Service | `{table}.services.js` | `PascalCase + Services` | `UsersServices` |
+| Controller | `{table}/{table}.controller.js` | `PascalCase + Controller` | `UsersController` |
+| Route | `{table}.router.js` | URL: `/kebab-case` | `/users`, `/products-invoices` |
+| Job | `{name}.js` (kebab-case) | `kebab-case` | `send-mail` |
+| Task | `{name}.js` (kebab-case) | — | `update-currencies.js` |
+| Middleware | `{name}.middleware.js` | — | `auth.middleware.js` |
+
+**Table names** use `snake_case` (matching the MySQL table name): `users`, `products_invoices`, `companies`.
+
+**File-to-URL conversion**: `products_invoices.router.js` → URL path `/products-invoices` (underscore to hyphen).
+
+**File-to-key conversion**: `products_invoices` → `ProductsInvoicesServices` / `ProductsInvoicesController` (snake_case to PascalCase + suffix).