@sentzunhat/zacatl 0.0.5 → 0.0.7

package/README.md

@@ -1,48 +1,58 @@
-# Zacatl
+# Zacatl Microservice Framework
 
 [![npm version](https://img.shields.io/npm/v/@sentzunhat/zacatl.svg)](https://www.npmjs.com/package/@sentzunhat/zacatl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](https://www.typescriptlang.org/)
 
-A blazing fast, minimal, and straightforward microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems. Zacatl provides a clean, modular architecture with robust typing support, letting you focus on business logic instead of infrastructure concerns.
+A modular, high-performance TypeScript microservice framework for Node.js, featuring layered architecture, dependency injection, and robust validation for building scalable APIs and distributed systems.
 
 ## Table of Contents
 
-- [Features](#features)
+- [Overview](#overview)
+- [Key Features](#key-features)
 - [Installation](#installation)
-- [Usage](#usage)
-- [Architecture](#architecture)
+- [Quick Start](#quick-start)
+- [Project Structure](#project-structure)
+- [Core Concepts](#core-concepts)
 - [Configuration](#configuration)
-- [API Reference](#api-reference)
 - [Testing](#testing)
 - [Contributing](#contributing)
+- [Documentation](#documentation)
 - [License](#license)
 
-## Features
+## Overview
 
-- **Fastify-based HTTP server**: Ultra-fast routing and extensibility
-- **Mongoose integration**: Easy MongoDB data modeling and repository pattern
-- **Modular architecture**: Clean separation of application, domain, infrastructure, and platform layers
-- **Dependency injection**: Powered by `tsyringe` for testability and flexibility
-- **Gateway support**: Proxy requests to upstream services with minimal setup
-- **Internationalization (i18n)**: Built-in support for multiple locales
-- **Comprehensive error handling**: Custom error classes and route error utilities
-- **Type-safe route handlers**: Strongly-typed REST entry points using Zod and Fastify
-- **Testing utilities**: Vitest configuration and helpers for fast, isolated unit tests
+Zacatl is a TypeScript-first microservice framework that enforces clean, layered (hexagonal) architecture with strict separation of concerns. It's designed for rapid development of robust APIs and distributed systems, with built-in support for dependency injection, validation, and seamless collaboration between human and AI contributors.
+
+## Key Features
+
+- **🏗️ Layered Architecture**: Clean separation with Application, Domain, Infrastructure, and Platform layers
+- **💉 Dependency Injection**: Built-in DI container using `tsyringe` for better modularity
+- **⚡ High Performance**: Built on Fastify for maximum speed and efficiency
+- **🔍 Type Safety**: Full TypeScript support with strict typing and generics
+- **✅ Validation**: Request/response validation using Zod schemas
+- **🧪 Testing**: Comprehensive testing with Vitest and clear test structure
+- **📊 MongoDB Support**: Built-in repository pattern with Mongoose integration
+- **🌐 Internationalization**: Multi-language support with i18n
+- **🚀 Production Ready**: Error handling, logging, and monitoring built-in
 
 ## Installation
 
+Install Zacatl using npm:
+
 ```bash
 npm install @sentzunhat/zacatl
-# or
+```
+
+Or with yarn:
+
+```bash
 yarn add @sentzunhat/zacatl
-# or
-bun install @sentzunhat/zacatl
 ```
 
-## Usage
+## Quick Start
 
-### Basic Setup
+Here's a minimal example to get you started:
 
 ```typescript
 import Fastify from "fastify";
@@ -84,131 +94,202 @@ const microservice = new MicroService({
 await microservice.start({ port: 9000 });
 ```
 
-### Creating Route Handlers
+For a complete example with route handlers, see our [examples](./examples) directory.
 
-```typescript
-import { z } from "zod";
-import { GetRouteHandler } from "@sentzunhat/zacatl";
+## Project Structure
 
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-});
+```
+src/
+├── configuration.ts         # App configuration and environment settings
+├── logs.ts                  # Structured logging with Pino
+├── optionals.ts             # Optional utility types and helpers
+├── error/                   # Custom error classes (BadRequest, NotFound, etc.)
+├── locales/                 # Internationalization files (en.json, fr.json)
+├── micro-service/
+│   └── architecture/
+│       ├── application/     # HTTP entry points, validation, route handlers
+│       ├── domain/          # Business logic, models, services (pure)
+│       ├── infrastructure/  # Database repositories, external adapters
+│       └── platform/        # Service orchestration, DI setup, startup
+└── utils/                   # Utility functions (base64, hmac, etc.)
+
+test/
+└── unit/                    # Unit tests mirroring src/ structure
+```
 
-type User = z.infer<typeof UserSchema>;
+### Layer Responsibilities
 
-class GetUserHandler extends GetRouteHandler<unknown, User, unknown> {
-  constructor() {
-    super({
-      url: "/users/:id",
-      schema: {
-        response: {
-          200: UserSchema,
-        },
-      },
-    });
-  }
-
-  async handler(request, reply): Promise<User> {
-    const userId = request.params.id;
-    // Fetch user from database, etc.
-    return {
-      id: userId,
-      name: "John Doe",
-      email: "john@example.com",
-    };
-  }
-}
-```
+- **Application Layer**: Handles HTTP requests, validation, and delegates to domain logic
+- **Domain Layer**: Contains pure business logic, models, and services (no infrastructure dependencies)
+- **Infrastructure Layer**: Manages persistence (MongoDB repositories) and external integrations
+- **Platform Layer**: Bootstraps the application, configures DI container, and starts the server
 
-### Database Integration
+---
 
-```typescript
-import { Schema } from "mongoose";
-import { singleton } from "tsyringe";
-import { BaseRepository } from "@sentzunhat/zacatl";
-
-interface Product {
-  name: string;
-  price: number;
-  description: string;
-}
-
-const productSchema = new Schema<Product>({
-  name: { type: String, required: true },
-  price: { type: Number, required: true },
-  description: { type: String, required: true },
-});
+## 3. Core Architectural Concepts
 
-@singleton()
-export class ProductRepository extends BaseRepository<Product> {
-  constructor() {
-    super({ name: "Product", schema: productSchema });
-  }
+- **Layered (Hexagonal) Architecture:**
+  - Platform → Application → Domain → Infrastructure
+  - Strict separation of concerns; each layer has a single responsibility.
+- **Error Handling:** All errors extend `CustomError` (see `src/error/`).
+- **Validation:** Use `zod` schemas for all request/response validation.
+- **Service Registration:** Register handlers/services in the DI container.
 
-  async findByName(name: string) {
-    return this.model.findOne({ name }).exec();
-  }
-}
-```
+---
 
-## Architecture
+## 4. Coding Standards for Humans and AI
+
+- **Naming:**
+  - Files/folders: lowercase, hyphens (e.g., `user-repository.ts`)
+  - Classes: PascalCase
+  - Functions/variables: camelCase, descriptive
+- **Code Style:**
+  - Clean, modular, and straightforward
+  - Use strong typing and TypeScript generics
+  - DRY principle: extract reusable logic
+  - Minimal comments; use tests to document behavior
+  - Validate all inputs and sanitize external data
+- **AI Patterns:**
+  - Replicate DI, modularity, and test structure
+  - Update YAML docs when generating new code
 
-The framework is organized into four main layers:
+---
 
-- **Application**: REST entry points (routes and hooks) and i18n configuration
-- **Domain**: Business logic providers and services
-- **Infrastructure**: Repositories and external dependencies
-- **Platform**: Service startup, database connections, and server configuration
+## 5. Dependency Injection (DI) Details
 
-Each layer is designed to be extensible and testable, supporting clean code principles.
+- **DI Container:** All services, repositories, and handlers are registered using `tsyringe`.
+- **No direct instantiation:** Always resolve dependencies via DI.
+- **AI Registration:** When generating new components, ensure they are registered in the DI container.
+
+---
 
-## Configuration
+## 6. Database Schema & Persistence
 
-- **Localization**: Place locale JSON files in `src/locales/` (e.g., `en.json`)
-- **Environment Variables**:
+- **MongoDB schemas:** Define all schemas in `src/micro-service/architecture/infrastructure/repositories/`.
+- **Repository pattern:** Extend `BaseRepository` for new collections.
+- **Schema best practices:**
+  - Favor embedding for related data
+  - Keep schemas minimal and property names concise
+  - Use references for large or independent data
+  - See `mongodb.yaml` for full guidelines
+
+---
+
+## 7. Error Management and Validation
+
+- **Error Classes:** All errors extend `CustomError` (see `src/error/`).
+- **Throw, don’t return:** Always throw errors for exceptional cases.
+- **Validation:** Use `zod` for all request/response validation. Place schemas in the Application layer.
+
+---
+
+## 8. Testing Philosophy and Setup
+
+- **Framework:** Use `vitest` for all tests.
+- **Structure:** Place tests in `test/unit/`, mirroring the `src/` structure.
+- **Mocking:** Mock all external dependencies (DB, services) in tests.
+- **AI Testing:** When generating new logic, always add or update tests.
+
+---
+
+## 9. Minimal Usage Example
+
+```typescript
+import Fastify from "fastify";
+import { MicroService } from "@sentzunhat/zacatl";
+
+const fastifyApp = Fastify();
+
+const microservice = new MicroService({
+  architecture: {
+    application: {
+      entryPoints: {
+        rest: {
+          hookHandlers: [], // Add hook handler classes
+          routeHandlers: [], // Add route handler classes
+        },
+      },
+    },
+    domain: { providers: [] }, // Add domain provider classes
+    infrastructure: { repositories: [] }, // Add repository classes
+    service: {
+      name: "my-service",
+      server: {
+        type: "SERVER",
+        vendor: "FASTIFY",
+        instance: fastifyApp,
+      },
+      databases: [
+        // Example for MongoDB:
+        // {
+        //   vendor: "MONGOOSE",
+        //   instance: new Mongoose(),
+        //   connectionString: "mongodb://localhost/mydb",
+        // }
+      ],
+    },
+  },
+});
+
+await microservice.start({ port: 9000 });
+```
+
+---
+
+## 10. Configuration and Environment Variables
+
+- **Localization:** Place locale JSON files in `src/locales/` (e.g., `en.json`)
+- **Environment Variables:**
   - `SERVICE_NAME` - Service name
   - `NODE_ENV` - Environment (development, production, test)
   - `CONNECTION_STRING` - Database connection string
 
-## API Reference
+---
 
-### Core Components
+## 11. Extending the Codebase (for Humans & AI)
 
-- `MicroService`: Central orchestrator for all architecture layers
-- `AbstractRouteHandler`: Base class for all route handlers
-- `BaseRepository`: Base class for MongoDB repositories
-- `CustomError`: Base class for typed error handling
+- Add new features by creating new handlers, services, or repositories in the appropriate layer.
+- Register all new classes in the DI container.
+- Write tests for all new logic.
+- Update YAML docs (`context.yaml`, `guidelines.yaml`, `patterns.yaml`, `mongodb.yaml`) with new patterns or conventions.
 
-## Testing
+---
 
-Run tests with:
+## 12. Documentation References
 
-```bash
-npm run test
-# or
-npm run test:coverage
-```
+- [`context.yaml`](./context.yaml): Architecture, components, and project context
+- [`guidelines.yaml`](./guidelines.yaml): Coding standards and best practices
+- [`patterns.yaml`](./patterns.yaml): Design and usage patterns
+- [`mongodb.yaml`](./mongodb.yaml): MongoDB schema guidelines
 
-Test configuration uses Vitest with in-memory MongoDB for isolated tests.
+---
 
-## Contributing
+## 13. Contributing Workflow
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+### For Humans
 
 1. Fork the repository
 2. Create your feature branch: `git checkout -b feature/amazing-feature`
 3. Commit your changes: `git commit -m 'Add some amazing feature'`
 4. Push to the branch: `git push origin feature/amazing-feature`
 5. Open a Pull Request
+6. Ensure all tests pass and docs are updated
 
-## License
+### For AI Agents
 
-MIT License © 2025 Sentzunhat - See the [LICENSE](./LICENSE) file for details.
+- Parse YAML docs for context and conventions
+- Register new code in the DI container
+- Add or update tests in `test/unit/`
+- Update YAML docs with new features or patterns
 
 ---
 
-Built by [Diego Beltran](https://sentzunhat.com) with [Fastify](https://fastify.io/), [Mongoose](https://mongoosejs.com/), and [tsyringe](https://github.com/microsoft/tsyringe).
+## 14. License and Maintainers
+
+- **License:** MIT License © 2025 Sentzunhat
+- **Maintainer:** Diego Beltran ([LinkedIn](https://www.linkedin.com/in/diego-beltran))
+- **Project URL:** [GitHub](https://github.com/sentzunhat/zacatl)
+
+---
 
-For questions or issues, please visit [GitHub](https://github.com/sentzunhat/zacatl/issues).
+_For all details, see the YAML documentation files above. Zacatl is designed for seamless collaboration between humans and AI agents._

package/context.yaml

@@ -0,0 +1,151 @@
+# Zacatl Project: Structured Context
+
+components:
+  - name: MicroService
+    type: class
+    file: src/micro-service/architecture/platform/micro-service.ts
+    description: |
+      The main orchestrator for the microservice. Bootstraps Application, Domain, Infrastructure, and Service layers. Handles startup, dependency registration, and handler registration.
+    methods:
+      - name: constructor
+        description: Initializes all architecture layers from config.
+      - name: start
+        description: Starts the service, configures databases, registers handlers, and launches the HTTP server.
+    dependencies:
+      - Application
+      - Domain
+      - Infrastructure
+      - Service
+
+  - name: Application
+    type: class
+    file: src/micro-service/architecture/application/application.ts
+    description: |
+      Handles HTTP entry points (REST), validation, and delegates to domain logic. Registers route and hook handlers using DI.
+    methods:
+      - name: constructor
+        description: Configures i18n and stores entry point config.
+      - name: start
+        description: Registers and stores REST hook and route handlers.
+    dependencies:
+      - AbstractArchitecture
+      - HookHandler
+      - RouteHandler
+
+  - name: Infrastructure
+    type: class
+    file: src/micro-service/architecture/infrastructure/infrastructure.ts
+    description: |
+      Registers and manages repositories (e.g., MongoDB) for persistence. Uses DI for repository registration.
+    methods:
+      - name: constructor
+        description: Stores repository config.
+      - name: start
+        description: Registers repositories in DI container.
+    dependencies:
+      - AbstractArchitecture
+
+  - name: BaseRepository
+    type: abstract class
+    file: src/micro-service/architecture/infrastructure/repositories/abstract.ts
+    description: |
+      Abstract base for MongoDB repositories. Handles model creation, lazy initialization, and CRUD methods. Ensures returned documents have an id field.
+    methods:
+      - name: constructor
+        description: Sets up Mongoose model and schema.
+      - name: findById
+        description: Finds a document by id and returns a lean object with id.
+      - name: create
+        description: Creates a new document and returns a lean object with id.
+      - name: update
+        description: Updates a document by id and returns a lean object with id.
+      - name: delete
+        description: Deletes a document by id and returns a lean object with id.
+    dependencies:
+      - mongoose
+      - tsyringe
+
+  - name: AbstractArchitecture
+    type: abstract class
+    file: src/micro-service/architecture/architecture.ts
+    description: |
+      Provides generic dependency registration helpers for all architecture layers. Enforces a start() contract.
+    methods:
+      - name: registerDependencies
+        description: Registers an array of classes in the DI container.
+      - name: registerAndStoreDependencies
+        description: Registers classes and stores resolved instances in a provided array.
+      - name: start
+        description: Abstract method to be implemented by subclasses.
+    dependencies:
+      - tsyringe
+
+  - name: CustomError
+    type: class
+    file: src/error/custom.ts
+    description: |
+      Base class for all custom errors. Supports metadata, error codes, and unique IDs. Used for structured error handling.
+    methods:
+      - name: constructor
+        description: Initializes error with message, code, reason, metadata, and stack trace.
+
+  - name: getConfigOrThrow
+    type: function
+    file: src/configuration.ts
+    description: |
+      Retrieves configuration values from the config system. Throws if missing.
+
+  - name: defaultLogger
+    type: object
+    file: src/logs.ts
+    description: |
+      Pino-based logger configured with environment and service metadata. Used for structured logging.
+
+  - name: Utility Exports
+    type: module
+    file: src/utils/index.ts
+    description: |
+      Exports utility functions (e.g., base64, hmac) for use throughout the codebase.
+
+layers:
+  - name: Platform
+    description: Bootstraps the app, configures DI, starts the server.
+    files:
+      - src/micro-service/architecture/platform/micro-service.ts
+      - src/micro-service/architecture/platform/service/service.ts
+  - name: Application
+    description: Handles HTTP requests, validation, delegates to domain logic.
+    files:
+      - src/micro-service/architecture/application/application.ts
+      - src/micro-service/architecture/application/entry-points/rest/route-handlers/
+      - src/micro-service/architecture/application/entry-points/rest/hook-handlers/
+  - name: Domain
+    description: Pure business rules, models, and logic (no infrastructure deps).
+    files:
+      - src/micro-service/architecture/domain/
+  - name: Infrastructure
+    description: Persistence (MongoDB repositories), external service integration.
+    files:
+      - src/micro-service/architecture/infrastructure/repositories/
+      - src/micro-service/architecture/infrastructure/infrastructure.ts
+
+patterns:
+  - Dependency Injection: All services, repositories, and handlers are registered in the DI container (tsyringe). Never instantiate dependencies directly.
+  - Error Handling: Custom error classes extend CustomError. Errors are thrown and bubble up to Fastify's error handler unless custom handling is needed.
+  - Validation: All request/response validation uses zod schemas.
+  - Testing: All business logic, handlers, and utilities are unit tested using vitest. Tests mirror the src/ structure.
+
+config:
+  - Localization: Locale JSON files in src/locales/ (e.g., en.json)
+  - Environment Variables:
+      - SERVICE_NAME: Service name
+      - NODE_ENV: Environment (development, production, test)
+      - CONNECTION_STRING: Database connection string
+      - APP_VERSION: Application version
+      - APP_ENV: Application environment
+
+testing:
+  - All tests are in test/unit/, mirroring src/ structure.
+  - Uses vitest for all tests.
+  - Mocks external dependencies (DB, services) in tests.
+  - Test helpers in test/unit/helpers/.

package/guidelines.yaml

@@ -0,0 +1,74 @@
+# Zacatl Project: Coding Guidelines & Best Practices
+
+naming:
+  file_folder:
+    - Use lowercase and hyphens (e.g., user-repository.ts, route-handlers/)
+  variables:
+    - Use meaningful, descriptive names
+  classes:
+    - Use PascalCase for class names
+  functions:
+    - Use camelCase for function and method names
+
+style:
+  - Write clean, modular, and straightforward code
+  - Use strong typing and TypeScript generics where appropriate
+  - Prefer async/await for asynchronous code
+  - Keep functions short, focused, and readable
+  - Prefer clarity over excessive comments; use tests to document behavior
+  - Avoid code duplication (DRY principle); extract reusable logic into utils/ or shared services
+  - Use modern TypeScript/ES features
+
+architecture:
+  - Follow layered (hexagonal) architecture: Platform → Application → Domain → Infrastructure
+  - Strict separation of concerns between layers
+  - Application: Handles HTTP, validation, delegates to domain
+  - Domain: Pure business logic, no infrastructure dependencies
+  - Infrastructure: Persistence, external integrations
+  - Platform: Bootstraps, configures DI, starts server
+
+patterns:
+  dependency_injection:
+    - Use tsyringe for all DI
+    - Register all services, repositories, and handlers in the DI container
+    - Never instantiate dependencies directly; always resolve via DI
+  error_handling:
+    - All custom errors extend CustomError (src/error/custom.ts)
+    - Use CustomError.handle(error) in middleware or route handlers to log/format errors
+    - Always include relevant metadata and a clear message in error instances
+    - Throw errors for exceptional cases; do not return error objects
+    - Let errors bubble up to Fastify’s error handler unless custom handling is needed
+  validation:
+    - Use zod schemas for all request/response validation
+  testing:
+    - Use vitest for all tests
+    - Place tests in test/, mirroring src/ structure
+    - Write unit tests for all logic
+    - Mock all external dependencies (DB, services) in tests
+    - Use descriptive test names and group related tests in files named after the module under test
+    - Run tests using the vitest CLI
+  documentation:
+    - Update context.yaml and guidelines.yaml with any new patterns, conventions, or architectural changes
+    - Document new features, patterns, or conventions in YAML, not Markdown
+
+mongodb:
+  - Define all schemas in infrastructure/repositories/
+  - Embed related data for performance when possible
+  - Keep schemas minimal and use concise property names
+  - Use references for large or independent data
+  - Ensure documents stay well below MongoDB’s 16MB limit
+  - Define indexes for frequently queried fields
+  - Use Mongoose and zod for schema and runtime validation
+  - Consider schema versioning for breaking changes
+
+extending:
+  - Add new features by creating new handlers, services, or repositories in the appropriate layer
+  - Register all new classes in the DI container
+  - Write tests for all new logic
+  - Update context.yaml and guidelines.yaml with new patterns or conventions
+
+security:
+  - Validate all inputs
+  - Handle errors gracefully
+  - Never expose sensitive data
+  - Sanitize and validate all external data

package/mongodb.yaml

@@ -0,0 +1,29 @@
+# Zacatl Project: MongoDB Schema Design Guidelines
+
+origin: mongodb_schema_design_guidelines.md
+source: MongoDB_schema_design_guidelines.pdf
+
+principles:
+  - favor_embedding:
+      rule: Embed related data within a single document when possible to improve performance by reducing the need for joins/queries.
+      rationale: Embedded documents ensure related data is retrieved together, enhancing read performance for one-to-few/one-to-many relationships.
+  - minimalism_and_simplicity:
+      rule: Design schemas with simplicity and minimalism. Use nested objects to reflect natural data hierarchies.
+      rationale: Minimal schemas are easier to understand, maintain, and scale.
+  - property_naming:
+      rule: Use single-word property names when possible; otherwise, limit to two words.
+      rationale: Short, concise property names reduce errors and improve readability.
+  - document_size_and_cardinality:
+      rule: Keep document size within MongoDB’s 16MB limit. Avoid embedding data that could grow unbounded (high-cardinality relationships).
+      rationale: Large documents degrade performance and complicate replication/backup. Use references for large/independent data.
+  - lifecycle_consistency:
+      rule: Embed data only if it shares a lifecycle with the parent document. Use references if embedded data is accessed/updated independently.
+      rationale: Aligning lifecycles ensures consistent, predictable schema behavior.
+
+flexibility:
+  - These guidelines are best practices and should be adapted to specific application requirements and data access patterns.
+  - The recommendation for concise property names is flexible, but clarity and consistency are critical.
+
+conclusion:
+  - Following these guidelines will help ensure MongoDB schemas are optimized for performance, maintainability, and scalability.
+  - Adapt as needed for your application’s needs.

package/package.json

@@ -2,12 +2,43 @@
   "name": "@sentzunhat/zacatl",
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"
   },
-  "description": "",
+  "description": "A modular, high-performance TypeScript microservice framework for Node.js, featuring layered architecture, dependency injection, and robust validation for building scalable APIs and distributed systems.",
+  "keywords": [
+    "typescript",
+    "microservice",
+    "microservices",
+    "framework",
+    "nodejs",
+    "dependency-injection",
+    "hexagonal-architecture",
+    "layered-architecture",
+    "clean-architecture",
+    "fastify",
+    "mongodb",
+    "mongoose",
+    "zod",
+    "validation",
+    "vitest",
+    "testing",
+    "api",
+    "rest-api",
+    "backend",
+    "server",
+    "enterprise",
+    "scalable",
+    "modular",
+    "tsyringe",
+    "pino",
+    "logging",
+    "i18n",
+    "internationalization",
+    "artisan"
+  ],
   "author": "Diego Beltran <beltrd@gmail.com> (https://sentzunhat.com)",
   "contributors": [
     {