@sentzunhat/zacatl

Zacatl Framework

Universal TypeScript framework for building APIs, CLI tools, and distributed systems.

Zacatl enforces layered (hexagonal) architecture with built-in dependency injection, type-safe validation, and structured error handling — designed for both human developers and AI agents to collaborate effectively.

What You Get

Capability	Detail
Layered Architecture	Strict Application → Domain → Infrastructure → Platform layers
Dependency Injection	Built-in DI container via tsyringe
Type-Safe Validation	Zod schema support; Yup and optional validation planned
Structured Errors	7 custom error types with correlation IDs
Pluggable ORM Adapters	Sequelize, Mongoose, built-in SQLite (Node 24+), or custom
Internationalization	Pluggable i18n with filesystem/memory adapters
Production Observability	Structured logging and error tracking
Tested	Vitest — test count and coverage shown in badges above

Architecture

┌─────────────────────────────────────────┐
│        Application Layer                │  HTTP handlers, validation, routes
├─────────────────────────────────────────┤
│        Domain Layer                     │  Business logic, services, models
├─────────────────────────────────────────┤
│        Infrastructure Layer             │  Repositories, database adapters
├─────────────────────────────────────────┤
│        Platform Layer                   │  DI container, service startup
└─────────────────────────────────────────┘

Dependencies flow strictly inward. The public API surface is stable; internal modules may change between minor versions.

Platform Support

Platform	Status
Server (HTTP)	Stable
CLI	Planned (stub only)
Desktop	Planned (stub only)

For non-HTTP scripts and workers today, use the standalone DI helpers from @sentzunhat/zacatl/dependency-injection directly.

Quick Start

npm install @sentzunhat/zacatl

Core server dependencies are installed with Zacatl. ORM/database adapters use optional peer dependencies (mongoose, sequelize, better-sqlite3, sqlite3, pg) that you install based on what your service uses.

import Fastify from 'fastify';
import { Service, ServiceType, ServerType, ServerVendor } from '@sentzunhat/zacatl';

const fastify = Fastify();

const service = new Service({
  type: ServiceType.SERVER,
  layers: {
    application: { entryPoints: { rest: { hooks: [], routes: [] } } },
    domain: { services: [] },
    infrastructure: { repositories: [] },
  },
  platforms: {
    server: {
      name: 'hello-service',
      server: { type: ServerType.SERVER, vendor: ServerVendor.FASTIFY, instance: fastify },
    },
  },
});

await service.start({ port: 3000 });

See examples/ for production-ready starters (Express, Fastify × SQLite, Postgres, MongoDB × React, Svelte).

Public API Modules

Module	Import path
Service	@sentzunhat/zacatl
Configuration	@sentzunhat/zacatl/configuration
Dependency Injection	@sentzunhat/zacatl/dependency-injection
Errors	@sentzunhat/zacatl
Logs	@sentzunhat/zacatl
Localization	@sentzunhat/zacatl
Third-party re-exports	@sentzunhat/zacatl/third-party/*

Documentation

Full docs live in docs/. New contributors start with START_HERE.md.

Topic	Link
Architecture Overview	docs/guidelines/framework-overview.md
Service Module	docs/service/README.md
Dependency Injection	docs/dependency-injection/README.md
Configuration	docs/configuration/README.md
Errors	docs/error/README.md
Logs	docs/logs/README.md
Localization	docs/localization/README.md
Third-Party + ORM	docs/third-party/README.md
ESLint	docs/eslint/README.md
Utils	docs/utils/README.md
Release Notes	docs/changelog.md

Testing

npm test                 # Run all tests
npm run test:coverage    # Coverage report

Requirements

• Node.js: 24.14.0+ (LTS)
• npm: 11.0.0+ (bundled with Node 24)
• TypeScript: 5.9+

Contributing

1. Open an issue describing the change.
2. Branch off it: git checkout -b issue-<number>/type/description
3. Add tests, update docs, commit with Conventional Commits.

See CONTRIBUTING.md for the full guide.

License

Apache License 2.0 2025 Zacatl Contributors

Zacatl is permissively licensed. Please don't use it to harm people.