ChaCC-API is an open‑source FastAPI‑based engine that enables developers to assemble backend services from interchangeable modules without recreating common setup code each time.

Core Architecture of ChaCC-API

The heart of ChaCC-API is a lightweight dispatcher that discovers, loads, and registers module packages at application start‑up. Each module follows a strict contract: a Python package exposing a router object and an optional init function. The dispatcher scans a designated directory, imports the package metadata, and injects the router into the main FastAPI instance. This approach keeps the core server free from business logic while granting modules full access to request handling, middleware, and background tasks.

Routing isolation is achieved through namespace prefixes that each module declares. For example, a user‑management module might expose routes under /users/*, while an analytics module occupies /metrics/*. The dispatcher automatically combines these prefixes, preventing accidental route collisions and preserving a clear URL hierarchy.

Configuration is driven by a single YAML file that lists enabled modules and supplies module‑specific settings. The file is parsed once, and the resulting dictionary is passed to each module's init function. Because the configuration format is uniform, adding a new module only requires editing this file and installing the package, eliminating the need to modify core code.

Internally, ChaCC-API relies on FastAPI for asynchronous request handling, Pydantic for data validation, and Starlette's lifespan events to manage start‑up and shutdown hooks. This stack provides high performance while keeping the engine approachable for developers familiar with modern Python web frameworks.

Module Lifecycle Management

Each module follows a clearly defined lifecycle: discovery, initialization, activation, and termination. During discovery, the dispatcher reads the module's pyproject.toml to verify version compatibility with the engine. Only modules that declare support for the current engine version are considered for loading, which protects the system from mismatched dependencies.

Initialization occurs after discovery and before activation. The module's init function receives the shared configuration object, allowing it to set up database connections, cache layers, or external API clients. Because the function runs in the same event loop as the main application, resources can be created asynchronously, reducing start‑up latency.

Activation registers the module's routes and any background tasks with the FastAPI app. At this stage, the module becomes visible to incoming traffic. If a module raises an exception during activation, the dispatcher logs the error, skips the module, and continues loading the remaining modules, ensuring that a single faulty component does not bring down the whole service.

Termination is invoked when the application receives a shutdown signal. Modules can release database pools, close file handles, or flush logs. By providing a standardized shutdown hook, ChaCC-API guarantees that resources are cleaned up consistently across all modules.

Dependency Acceleration with chacc-dependency-manager

ChaCC-API ships with a small helper library named chacc-dependency-manager. This tool acts as a pip accelerator, caching wheels locally and reusing them across module installations. When a new module is added, the manager checks the local cache before contacting PyPI, dramatically reducing install time for frequently used packages.

The manager also enforces a lock‑file policy similar to poetry.lock. When a module specifies its dependencies, the manager resolves version constraints once and records the exact versions in a chacc.lock file. Subsequent installations reference this lock file, guaranteeing reproducible environments and preventing accidental upgrades that could break the engine.

Although the library is lightweight, it provides useful diagnostics. During installation, it prints a concise table of resolved packages, source locations, and any conflicts detected. This output helps developers understand why a particular version was chosen without digging through verbose pip logs.

Because the manager operates as a thin wrapper around pip, it does not replace established dependency tools instead, it complements them by offering speed improvements for the specific workflow of ChaCC-API modules.

Configuration and Extensibility

The YAML configuration file supports hierarchical overrides, allowing global defaults to be superseded by module‑level settings. For instance, a global database_url can be overridden by a module that requires a separate read‑replica. The engine merges these settings using a deep‑merge algorithm, preserving nested structures while applying overrides where needed.

Extensibility is further enhanced through a plugin system based on entry points defined in setup.cfg. Developers can publish third‑party extensions that the dispatcher automatically discovers. These extensions can add custom validation rules, provide alternative authentication backends, or inject telemetry hooks without modifying the core code.

To illustrate integration with external services, the documentation includes a guide that shows how to connect a module to a preset annotation framework. By referencing the preset library, a module can inherit standardized field definitions and UI hints, reducing duplication across the code base.

Security considerations are baked into the configuration schema. Required fields such as secret_key are marked as sensitive, and the engine masks their values in logs. Additionally, the schema supports optional TLS settings, enabling developers to enforce encrypted communication for modules that expose external endpoints.

Testing Strategies and CI Integration

ChaCC-API encourages a test‑first approach by providing a pytest fixture that spins up a temporary FastAPI instance with a subset of modules. Tests can import this fixture and perform end‑to‑end requests against the live router, verifying both request handling and module interaction.

Continuous integration pipelines can leverage the fixture alongside the chacc-dependency-manager cache. By restoring the cache at the start of a job, CI runners avoid re‑downloading large wheels, resulting in faster feedback cycles. The pipeline also runs a linting step that checks module metadata for missing entry points or version mismatches.

For performance regression detection, the repository includes a simple benchmark script that measures request latency for each registered route. The script records results in a JSON file that can be uploaded to a monitoring dashboard, allowing teams to spot slowdowns introduced by new modules.

Documentation generation is automated using Cloudflare One integration, which publishes the generated OpenAPI schema to a hosted endpoint. Consumers can retrieve the schema programmatically, ensuring that client libraries stay in sync with the evolving API surface.

Community Adoption and Contribution Guidelines

Open source success relies on clear contribution pathways. ChaCC-API maintains a CONTRIBUTING.md file that outlines steps for forking the repository, setting up a development environment, and submitting pull requests. The file emphasizes the importance of writing unit tests for any new functionality and updating the documentation accordingly.

Issues are categorized using labels such as bug, enhancement, and module‑request. This taxonomy helps maintainers prioritize work and allows contributors to find tasks that match their skill level. A dedicated discussion board on GitHub Discussions hosts design debates, feature proposals, and usage showcases.

To lower the barrier for first‑time contributors, the project includes a good first issue tag on tickets that require modest changes, such as fixing type hints or improving error messages. These tickets often come with step‑by‑step instructions, making onboarding straightforward.

Community members are encouraged to publish their own modules to the public chaCC-modules index. Published modules must include a pyproject.toml that declares compatibility with the current engine version and a short README describing the module's purpose. By fostering a marketplace of reusable components, ChaCC-API extends its value beyond a single repository.