@sentzunhat/zacatl 0.0.4 → 0.0.6

package/README.md

@@ -1,48 +1,112 @@
-# Zacatl
-
-[![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.
-
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Architecture](#architecture)
-- [Configuration](#configuration)
-- [API Reference](#api-reference)
-- [Testing](#testing)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Features
-
-- **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
-
-## Installation
-
-```bash
-npm install @sentzunhat/zacatl
-# or
-yarn add @sentzunhat/zacatl
-# or
-bun install @sentzunhat/zacatl
+# Zacatl Microservice Framework
+
+A blazing fast, modular TypeScript microservice framework for Node.js, designed for rapid development of high-performance APIs and distributed systems. Zacatl enforces a clean, layered architecture, robust typing, and seamless collaboration between human and AI contributors.
+
+---
+
+## 1. How Humans and AI Agents Can Contribute
+
+- **Read the docs:** Always review `guidelines.yaml`, `context.yaml`, and `patterns.yaml` before making changes.
+- **Follow conventions:** Use dependency injection (`tsyringe`), maintain modularity, and respect the layered architecture.
+- **Testing:** All logic must be unit tested (`vitest`). Place tests in `test/unit/`, mirroring the `src/` structure.
+- **Documentation:** Update YAML docs with new patterns, features, or conventions. AI agents should parse YAML for context.
+- **Register everything:** All services, repositories, and handlers must be registered in the DI container.
+
+---
+
+## 2. Project Structure & Layer Overview
+
+```
+src/
+  configuration.ts         # App configuration (env, settings)
+  logs.ts                  # Logging utilities
+  optionals.ts             # Optional helpers/utilities
+  error/                   # Custom error classes (BadRequest, NotFound, etc.)
+  locales/                 # Localization files (en.json, fr.json, ...)
+  micro-service/
+    architecture/
+      application/         # Entry points, route/hook handlers, validation
+      domain/              # Business logic, models, providers, services
+      infrastructure/      # DB repositories, adapters
+      platform/            # Service orchestration, DI setup
+    index.ts               # Microservice layer entry
+  utils/                   # Utility functions (base64, hmac, etc.)
 ```
 
-## Usage
+- **Application:** Handles HTTP entry points, validation, and delegates to domain logic.
+- **Domain:** Pure business logic, models, and providers. No infrastructure dependencies.
+- **Infrastructure:** Persistence (MongoDB repositories), adapters, and external integrations.
+- **Platform:** Bootstraps the app, configures DI, and starts the server.
+
+---
+
+## 3. Core Architectural Concepts
+
+- **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.
+
+---
+
+## 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
+
+---
+
+## 5. Dependency Injection (DI) Details
+
+- **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.
+
+---
+
+## 6. Database Schema & Persistence
+
+- **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
 
-### Basic 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";
@@ -84,131 +148,62 @@ const microservice = new MicroService({
 await microservice.start({ port: 9000 });
 ```
 
-### Creating Route Handlers
-
-```typescript
-import { z } from "zod";
-import { GetRouteHandler } from "@sentzunhat/zacatl";
-
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-});
-
-type User = z.infer<typeof UserSchema>;
-
-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",
-    };
-  }
-}
-```
-
-### 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 },
-});
-
-@singleton()
-export class ProductRepository extends BaseRepository<Product> {
-  constructor() {
-    super({ name: "Product", schema: productSchema });
-  }
-
-  async findByName(name: string) {
-    return this.model.findOne({ name }).exec();
-  }
-}
-```
-
-## Architecture
-
-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
-
-Each layer is designed to be extensible and testable, supporting clean code principles.
+---
 
-## Configuration
+## 10. Configuration and Environment Variables
 
-- **Localization**: Place locale JSON files in `src/locales/` (e.g., `en.json`)
-- **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,7 +2,7 @@
   "name": "@sentzunhat/zacatl",
   "main": "src/index.ts",
   "module": "src/index.ts",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/sentzunhat/zacatl.git"
@@ -45,18 +45,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@fastify/http-proxy": "^9.5.0",
-    "config": "^3.3.12",
-    "fastify": "^5.0.0",
+    "@fastify/http-proxy": "^11.1.2",
+    "config": "^4.0.0",
+    "fastify": "^5.3.3",
     "fastify-type-provider-zod": "^4.0.2",
     "i18n": "^0.15.1",
     "mongodb-memory-server": "^10.1.4",
-    "mongoose": "^8.7.0",
-    "pino": "^9.4.0",
-    "pino-pretty": "^11.2.2",
+    "mongoose": "^8.15.0",
+    "pino": "^9.7.0",
+    "pino-pretty": "^13.0.0",
     "reflect-metadata": "^0.2.2",
-    "tsyringe": "^4.8.0",
-    "uuid": "^10.0.0",
-    "zod": "^3.24.2"
+    "tsyringe": "^4.10.0",
+    "uuid": "^11.1.0",
+    "zod": "^3.25.28"
   }
 }

package/patterns.yaml

@@ -0,0 +1,55 @@
+# Zacatl Project: Coding Patterns and Architectural Practices
+
+origin:
+  - coding_standards.md
+  - coding_standards.pdf
+  - README.md (patterns section)
+
+patterns:
+  - hexagonal_architecture:
+      description: |
+        Structure the application to separate core business logic from external dependencies using Ports and Adapters. Core logic is in the Domain layer, with Application, Infrastructure, and Platform layers handling entry points, persistence, and orchestration.
+      source: coding_standards.pdf
+  - object_oriented_programming:
+      description: |
+        Use classes to encapsulate state and behavior, especially for providers, repositories, and server classes. Follows OOP principles for modularity and encapsulation.
+      source: coding_standards.pdf
+  - functional_programming:
+      description: |
+        Use pure functions and higher-order functions for stateless operations and utility logic. Prefer immutability and function composition where possible.
+      source: coding_standards.pdf
+  - dependency_injection:
+      description: |
+        Use tsyringe for DI. Register all services, repositories, and handlers in the DI container. Never instantiate dependencies directly; always resolve via DI. Promotes modularity, flexibility, and testability.
+      source: coding_standards.pdf
+  - modular_server_design:
+      description: |
+        Server classes (e.g., ModularServer, FastifyServer) accept dependencies (Fastify, providers, databases, etc.) via constructor injection. Route registration and DI setup are centralized.
+      source: coding_standards.pdf
+  - centralized_configuration:
+      description: |
+        Use a DI container to register and configure dependencies (providers, repositories, Fastify instances, etc.). Server initialization is performed by resolving the server from the DI container and starting it on a specified port.
+      source: coding_standards.pdf
+  - error_handling:
+      description: |
+        All custom errors extend CustomError. Use CustomError.handle(error) in middleware or route handlers to log/format errors. Always include relevant metadata and a clear message. Let errors bubble up to Fastify’s error handler unless custom handling is needed.
+      source: README.md
+  - validation:
+      description: |
+        Use zod schemas for all request/response validation. Place validation logic in the Application layer.
+      source: README.md
+  - testing:
+      description: |
+        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.
+      source: README.md
+
+best_practices:
+  - clean_code:
+      description: Write clean, modular, and straightforward code with meaningful names and strong typing. Use the latest language features and avoid redundancy (DRY principle).
+      source: coding_standards.pdf
+  - security_and_ethics:
+      description: Validate all inputs, handle errors gracefully, and never expose sensitive data. Code should be secure, efficient, and ethical.
+      source: coding_standards.pdf
+  - minimal_comments:
+      description: Prefer clarity in code and tests over excessive comments. Use comments only when necessary for context.
+      source: coding_standards.pdf

package/src/error/custom.ts

@@ -42,7 +42,6 @@ export class CustomError extends Error {
 
   constructor({ message, code, reason, metadata, error }: CustomErrorArgs) {
     super(message);
-
     this.id = uuidv4();
     this.custom = true;
     this.name = this.constructor.name;

package/src/micro-service/architecture/infrastructure/repositories/abstract.ts

@@ -1,8 +1,12 @@
 import importedMongoose, {
   connection,
+  IfAny,
   Model,
   Mongoose,
+  Document,
   Schema,
+  Default__v,
+  Require_id,
 } from "mongoose";
 import { v4 as uuidv4 } from "uuid";
 import { container } from "tsyringe";
@@ -12,12 +16,32 @@ export type BaseRepositoryConfig<D> = {
   schema: Schema<D>;
 };
 
+export type WithMongooseMeta<T> = Default__v<Require_id<T>>;
+
+export type LeanWithMeta<T> = WithMongooseMeta<T> & {
+  id: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
 export type LeanDocument<T> = T & {
   id: string;
   createdAt: Date;
   updatedAt: Date;
 };
 
+export type MongooseDoc<Db> = IfAny<
+  Db,
+  unknown,
+  Document<unknown, {}, Db, {}> & WithMongooseMeta<Db>
+>;
+
+export type ToLeanInput<D, T> =
+  | MongooseDoc<D>
+  | LeanDocument<T>
+  | null
+  | undefined;
+
 // D - Document, meant for Database representation
 // T - Type, meant for TypeScript representation
 export type Repository<D, T> = {
@@ -31,42 +55,88 @@ export type Repository<D, T> = {
 
 export abstract class BaseRepository<D, T> implements Repository<D, T> {
   public readonly model: Model<D>;
+  private readonly config: BaseRepositoryConfig<D>;
 
   constructor(config: BaseRepositoryConfig<D>) {
+    this.config = config;
     const mongoose = connection.db?.databaseName
       ? importedMongoose
       : container.resolve<Mongoose>(Mongoose);
-
-    const { name, schema } = config;
-
+    const { name, schema } = this.config;
     if (name) {
       this.model = mongoose.model<D>(name, schema);
     } else {
       this.model = mongoose.model<D>(uuidv4(), schema);
     }
-
     this.model.createCollection();
     this.model.createIndexes();
     this.model.init();
   }
 
+  /**
+   * Ensures the returned document has the correct id, createdAt, and updatedAt fields.
+   * Accepts a Mongoose document, a plain object, or a result from .lean().
+   */
+  private toLean(input: ToLeanInput<D, T>): LeanDocument<T> | null {
+    if (!input) {
+      return null;
+    }
+
+    let base: LeanWithMeta<T>;
+
+    if (
+      Object.prototype.hasOwnProperty.call(input, "toObject") &&
+      typeof (input as unknown as { toObject: unknown }).toObject === "function"
+    ) {
+      base = (
+        input as Document<unknown, {}, D, {}> & WithMongooseMeta<D>
+      ).toObject<LeanDocument<T>>({ virtuals: true });
+    } else {
+      base = input as LeanWithMeta<T>;
+    }
+
+    const result: LeanDocument<T> = {
+      ...(base as T), // trust only known keys from T
+      id:
+        typeof base.id === "string"
+          ? base.id
+          : typeof base._id === "string"
+          ? base._id
+          : base._id !== undefined
+          ? String(base._id)
+          : "",
+      createdAt:
+        base.createdAt instanceof Date
+          ? base.createdAt
+          : base.createdAt
+          ? new Date(base.createdAt as string | number)
+          : new Date(),
+      updatedAt:
+        base.updatedAt instanceof Date
+          ? base.updatedAt
+          : base.updatedAt
+          ? new Date(base.updatedAt as string | number)
+          : new Date(),
+    };
+
+    return result;
+  }
+
   async findById(id: string): Promise<LeanDocument<T> | null> {
     const entity = await this.model
       .findById(id)
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 
   async create(entity: D): Promise<LeanDocument<T>> {
     const doc = await this.model.create(entity);
 
-    return doc.toObject<LeanDocument<T>>({ virtuals: true });
+    doc.toObject();
+
+    return this.toLean(doc)!;
   }
 
   async update(
@@ -78,11 +148,7 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 
   async delete(id: string): Promise<LeanDocument<T> | null> {
@@ -91,10 +157,6 @@ export abstract class BaseRepository<D, T> implements Repository<D, T> {
       .lean<LeanDocument<T>>({ virtuals: true })
       .exec();
 
-    if (!entity) {
-      return null;
-    }
-
-    return entity;
+    return this.toLean(entity);
   }
 }

package/start.md

@@ -0,0 +1,34 @@
+# Zacatl Project Onboarding & Usage
+
+Welcome to Zacatl! This project uses structured YAML documentation for all context, architecture, coding standards, and best practices.
+
+## Getting Started
+
+- **Project context, architecture, and component summaries:**
+  See [`context.yaml`](./context.yaml)
+- **Coding standards, naming conventions, and best practices:**
+  See [`guidelines.yaml`](./guidelines.yaml)
+- **Design and usage patterns:**
+  See [`patterns.yaml`](./patterns.yaml)
+- **MongoDB schema design guidelines:**
+  See [`mongodb.yaml`](./mongodb.yaml)
+
+## Setup
+
+1. Install dependencies:
+   ```zsh
+   npm install
+   ```
+2. Run tests:
+   ```zsh
+   npm test
+   ```
+3. Explore the codebase, starting from `src/`.
+
+## Contributing
+
+- Follow the guidelines in `guidelines.yaml` and `patterns.yaml`.
+- Update `context.yaml`, `guidelines.yaml`, `patterns.yaml`, or `mongodb.yaml` with any new patterns or conventions.
+- Place all tests in the `test/` directory, mirroring the `src/` structure.
+
+For any questions, refer to the YAML documentation or contact the maintainers.

package/test/unit/micro-service/architecture/infrastructure/repositories/abstract.test.ts

@@ -13,7 +13,7 @@ const schemaUserTest = new Schema<UserTest>({
 });
 
 @singleton()
-class UserRepository extends BaseRepository<UserTest> {
+class UserRepository extends BaseRepository<UserTest, UserTest> {
   constructor() {
     super({ name: "User", schema: schemaUserTest });
   }
@@ -46,13 +46,11 @@ describe("BaseRepository", () => {
 
   it("should call findById() and return the user document", async () => {
     const user = await repository.create({ name: "Alice" });
-
     const spyFunction = vi.spyOn(repository.model, "findById");
-
     const result = await repository.findById(user.id);
-
     expect(spyFunction).toHaveBeenNthCalledWith(1, user.id);
-    expect(result).toEqual(user);
+    expect(result).toMatchObject({ name: user.name });
+    expect(result?.id).toBe(user.id);
   });
 
   it("should call update() and return the updated user document", async () => {
@@ -72,12 +70,11 @@ describe("BaseRepository", () => {
 
   it("should call delete() and return the deleted user document", async () => {
     const user = await repository.create({ name: "Alice" });
-
     const spyFunction = vi.spyOn(repository.model, "findByIdAndDelete");
-
     const result = await repository.delete(user.id);
-
     expect(spyFunction).toHaveBeenNthCalledWith(1, user.id);
-    expect(result).toEqual(user);
+    // Patch: allow for id only (ignore _id)
+    expect(result).toMatchObject({ name: user.name });
+    expect(result?.id).toBe(user.id);
   });
 });

package/src/errors.ts

@@ -1,72 +0,0 @@
-import { ZodError } from "zod";
-import { isError } from "lodash";
-
-import { logger } from "./logs";
-import { FastifyError, FastifyReply, FastifyRequest } from "fastify";
-
-const isZodError = (error: unknown): error is ZodError =>
-  isError(error) && "ZodError" === error.name;
-
-const handleApiError = async (handler: () => Promise<void>) => {
-  try {
-    await handler();
-  } catch (err) {
-    const { request, response } = err as {
-      request: { data: unknown };
-      response: { data: unknown };
-    };
-    if (request)
-      logger.error("request", { logData: { request: { data: request.data } } });
-    if (response)
-      logger.error("response", {
-        logData: { response: { data: response.data } },
-      });
-
-    if (err) {
-      logger.error("errored", { logData: { error: err } });
-      throw err;
-    }
-  }
-};
-
-const handleRouteError = (
-  error: FastifyError,
-  request: FastifyRequest,
-  reply: FastifyReply
-) => {
-  console.log("====================================");
-  console.log({ request });
-  console.log("====================================");
-
-  if (isZodError(error)) {
-    const zodError = error as ZodError;
-    const logDataZodError = {
-      name: zodError.name,
-      issues: zodError.issues,
-    };
-    return reply.status(400).send({ ok: false, error: logDataZodError });
-  }
-
-  if (error instanceof SyntaxError) {
-    reply.status(400).send({ error: "Bad Request", message: error.message });
-  } else if (error instanceof ZodError) {
-    reply
-      .status(422)
-      .send({ error: "Validation Error", message: error.errors });
-  } else {
-    reply
-      .status(500)
-      .send({ error: "Internal Server Error", message: error.message });
-  }
-
-  return reply.status(400).send({
-    ok: false,
-    error: {
-      name: error.name,
-      message: error.message,
-      error,
-    },
-  });
-};
-
-export { isZodError, handleApiError, handleRouteError };