Python API overview

This page covers the Cadrumo Python package boundary for contributors: which layers exist, what each one owns, and where to start reading before following a link into the generated module reference. It is part of the full documentation build only; taxpayer-facing builds exclude the API tree.

Cadrumo is a hexagonal application. Dependencies point inward: adapters and entry points depend on the application and domain layers, never the reverse. The generated reference mirrors the package tree, so the curated map below is the fastest way to land in the right subpackage.

Layers

  • cadrumo.core owns the shared spine: typed identifiers and closed-value enums (Modelo, period codes, source kinds), the JSON envelope contract, settings, and the product identity authority. Every other layer may import it; it imports none of them.

  • cadrumo.domain owns tax semantics: the modelo registry compiler and its validated authority, calculation formulas and bindings, deadlines, and taxpayer records. Domain logic stays independent from adapters.

  • cadrumo.application owns orchestration: filing workflows, calculation actions, the ledger, verification, exports, and the secure-storage services that compose domain primitives into operator verbs.

  • cadrumo.adapters owns the boundary implementations: inbound parsers (bank statements, borrador and justificante documents) and outbound integrations (the AEAT sede, Google Sheets, LLM providers).

  • cadrumo.entrypoints owns the process surfaces: the aeat command-line interface and the cadrumo-mcp Model Context Protocol server. Both drive the same application services.

Where to start

Read a feature top-down: find its operator verb in the CLI entry point, follow it into the application service it calls, then into the domain primitives that service composes. Cross-package imports resolve through each package’s public top-level facade, so a package’s __init__ is its table of contents.

The complete generated tree starts at the cadrumo package root. The stubs are regenerated by the dev.docs.apidocs scaffolder; never edit them by hand.