core-api-consumers-architecture

Core-API-Consumers Architecture

Build Python desktop + AI-agent applications using three strict layers: Core -> API -> Consumers (GUI, CLI, MCP).

When to Use This Skill

Use when the user asks to:

• Create a new Python package from scratch
• Add a feature to an existing layered package
• Build or extend an API orchestration layer
• Create an MCP (Model Context Protocol) server for AI agent access
• Wire a PyQt5/6 GUI to a headless API
• Scaffold a CLI for scripting and automation
• Restructure a monolithic app into clean layers
• Review code for architecture compliance

Architecture Overview

Consumers (outer)
  GUI (PyQt5)  |  CLI (argparse)  |  MCP (FastMCP)
       \              |               /
        v             v              v
  +--------------------------------------+
  |           API  Layer                 |   <- orchestration
  |  config  |  *_ops  |  session_io    |
  +--------------------------------------+
                    |
                    v
  +--------------------------------------+
  |           CORE  Layer                |   <- pure logic
  |  models | engines | processing | io  |
  +--------------------------------------+

The Dependency Rule

Dependencies flow inward only. NEVER violate this.

• Core NEVER imports from API, GUI, CLI, or MCP.
• API NEVER imports from GUI, CLI, or MCP.
• Data flows outward via return values and callbacks — never via imports.

Project Scaffolding

When creating a new package, use this directory layout:

my_package/
├── __init__.py
├── core/
│   ├── __init__.py
│   ├── models.py           # Dataclasses / domain entities
│   ├── engines/            # Computational engines (one per domain)
│   ├── processing/         # Signal processing, QC, statistics
│   ├── io/                 # File format readers/writers
│   └── utils.py            # Pure utility functions
├── api/
│   ├── __init__.py
│   ├── config.py           # All configuration dataclasses
│   ├── analysis.py         # Main workflow operation functions
│   ├── export.py           # Export / report operations
│   ├── session_io.py       # Session save/load
│   └── validation.py       # Input validation
├── gui/
│   ├── __init__.py
│   ├── main_window.py
│   ├── views/              # Major UI panels (one per tab / screen)
│   ├── dialogs/            # Modal configuration dialogs
│   └── widgets/            # Reusable custom widgets
├── cli/
│   ├── __init__.py
│   └── main.py
├── mcp/
│   ├── __init__.py
│   ├── __main__.py         # Entry: python -m my_package.mcp
│   └── server.py           # FastMCP tool definitions
└── visualization/          # Optional: plot functions
    ├── __init__.py
    └── plots.py

Layer Responsibilities

Core Layer (core/)

Pure domain logic. No framework imports. No UI. No network.

Sub-module	Responsibility
models.py	Dataclasses for domain entities
engines/	Stateless computational algorithms
processing/	Signal processing, QC, statistics
io/	File format readers/writers
utils.py	Pure helpers (unit conversion, interpolation)

Rules: Functions take data in, return data out. No side effects. No global state. Testable with plain pytest.

For detailed code examples, read references/core-layer.md.

API Layer (api/)

Orchestration and configuration. The single entry point for all consumers.

Sub-module	Responsibility
config.py	Dataclass-based configuration objects
*_ops.py	Operation functions — one per workflow
session_io.py	Session save/load (serialize to disk)
validation.py	Input validation before calling core

Rules:

1. Every operation returns {"success": bool, "errors": [...], ...}.
2. Accept a progress_callback for GUI progress bars (optional, default None).
3. Catch all core exceptions — never let them bubble to consumers.
4. Use absolute file paths only.
5. Validate inputs BEFORE calling core.

Critical defaults:

• Statistics: lognormal (log-space median). Never arithmetic mean as default.
• Peak basis: median curve. Never mean as default.
• All params have sensible defaults — a bare Config() must work.

For detailed code examples, read references/api-layer.md.

GUI Layer (gui/)

PyQt5/6 widgets. Zero business logic. Only event wiring and display.

1. Read user input -> build config dataclass -> call API function -> display result.
2. Never call core directly — always go through API.
3. Never block the main thread — use QThread worker for any call > 100ms.
4. Config objects are the contract between GUI and API.

For QThread worker pattern and common pitfalls, read references/gui-layer.md.

CLI Layer (cli/)

argparse or click based. Parses arguments -> builds config -> calls API -> prints result. Same API functions as GUI and MCP.

MCP Layer (mcp/)

FastMCP server exposing API operations as AI-agent-callable tools.

1. Each tool is a thin wrapper around one API function.
2. Use session_id for stateful multi-call workflows.
3. Config-setting tools accept Optional params — only update what is provided.
4. All returns must be JSON-serializable dicts.
5. NEVER use multiprocessing.Pool — it deadlocks stdio transport.
6. Tool docstrings are critical — the AI agent reads them to choose tools.

For complete MCP server pattern, read references/mcp-layer.md.

Visualization Layer (visualization/)

Optional sibling. Plot functions take arrays + output path -> return saved file path. Called by API in report/export operations. Never imports from GUI/CLI/MCP.

Adding a New Feature

Always follow this order:

1. CORE    ->  Add algorithm / data model / loader
2. API     ->  Add operation function + config fields
3. GUI     ->  Add widget / dialog that calls the API
4. CLI     ->  Add subcommand that calls the API
5. MCP     ->  Add tool that calls the API

Each step is independently testable and deployable. A feature can exist in API+CLI before the GUI is built. MCP can be added without touching core.

For a complete worked example, read references/feature-workflow.md.

Error Handling Strategy

Layer	Strategy
Core	Raise domain-specific exceptions
API	Catch all -> return {"success": false, "errors": [...]}
GUI	Read errors -> show QMessageBox
CLI	Read errors -> print to stderr -> exit(1)
MCP	Return error dict -> AI agent reads and adapts

QC Failure Fallback (important pattern)

When quality control rejects too many items, the API should auto-fallback:

1. First try: full QC enabled.
2. Fallback 1: disable aggressive checks (e.g., STA/LTA).
3. Fallback 2: disable all QC, add warning to result.

For implementation, read references/error-handling.md.

Batch Processing

For multi-item workflows, the API iterates over items calling the single-item API function. In MCP context, never use multiprocessing.Pool — use sequential processing or ThreadPoolExecutor.

Testing Strategy

tests/
├── test_core/     # Unit tests — fast, no I/O, no framework
├── test_api/      # Integration tests — may use tmp_path for files
└── test_mcp/      # Tool tests — call functions with mock data

Core tests are pure. API tests may touch disk. GUI tests are optional (pytest-qt).

Configuration Conventions

• ALL tunable params live in dataclass configs in api/config.py.
• Master config composes sub-configs: ProcessingConfig, QCConfig, PeakConfig, etc.
• JSON serialization via dataclasses.asdict() / recursive config_from_dict().
• dict.get(key, default) returns None when key EXISTS with value None. Always guard: cfg.get(k, d) or d for PyQt5 setValue() calls.

File Path Conventions

• Always use absolute paths in API functions.
• Use os.path.join or pathlib.Path — never string concatenation.
• Validate paths early in the API validation step.
• On Windows: accept both / and \, normalize for display.

Implementation Checklist

When implementing any feature, verify:

• Algorithm is in core/ with zero framework imports
• Config fields in api/config.py with sensible defaults
• API operation returns {"success": bool, "errors": [...]}
• API validates inputs before calling core
• GUI calls API via QThread worker (never blocks main thread)
• CLI builds config from args -> calls same API function
• MCP tool wraps API function, uses session_id, returns dict
• Dependencies flow inward only (core <- API <- consumers)
• Tests exist for core (unit) and API (integration)