TaipanStack Architecture¶

TaipanStack is built on the philosophy of maximum safety by default, combined with blazing-fast asynchronous programming. The internal architecture enforces a strict layered dependency map, statically verified on every commit.

🤖 AI Agents Note: AI assistants modifying architectural components must abide by the rules detailed in the AI Agents Guidelines.

Layered Dependency Model¶

The architecture enforces unidirectional data flow. Upper layers may import from lower layers; lower layers may never import upward.

graph TD
    A["🏢 Application Layer<br/>(your business logic)"]
    B["🛡️ Security Layer<br/>guards · sanitizers · validators · decorators"]
    C["⚙️ Config Layer<br/>models · generators · version_config"]
    D["🔧 Utils Layer<br/>logging · filesystem · context"]
    E["🎯 Core Layer<br/>result · compat · optimizations"]
    F["🌊 Resilience Layer<br/>circuit_breaker · retry · watchdogs"]
    G["🌉 Bridges Layer<br/>http · db"]

    A --> B
    A --> C
    A --> D
    A --> F
    A --> G
    F --> D
    F --> E
    G --> B
    G --> F
    B --> E
    C --> E
    D --> E

    style A fill:#4A148C,color:#fff
    style B fill:#880E4F,color:#fff
    style C fill:#1A237E,color:#fff
    style D fill:#004D40,color:#fff
    style E fill:#BF360C,color:#fff
    style F fill:#006064,color:#fff
    style G fill:#E65100,color:#fff

Dependency Contracts (Import Linter)¶

These contracts are enforced statically in CI via Import Linter. Any violation fails the build immediately.

Contract	Rule
`core` is independent	`taipanstack.core` cannot import from `security`, `utils`, `config`, or `resilience`
`security` is independent	`taipanstack.security` cannot import from `utils`, `config`, or `resilience`
`utils` is independent	`taipanstack.utils` cannot import from `security`, `config`, or `resilience`
`config` only uses `core`	`taipanstack.config` cannot import from `security`, `utils`, or `resilience`
`resilience` only uses `core`	`taipanstack.resilience` cannot import from `security` or `config`
`bridges` isolation	`taipanstack.bridges` cannot import from `config`

Project Structure¶

TaipanStack/
├── src/
│   └── taipanstack/
│       ├── __init__.py       # Public API surface
│       ├── bridges/          # 🌉 External communication integrations
│       │   ├── http_bridge.py     #    Safe HTTP client
│       │   ├── db_bridge.py       #    Resilient database connector
│       │   └── web_bridge.py      #    Result-to-HTTP response utilities
│       ├── config/           # ⚙️ Configuration models & generators
│       │   ├── models.py     #    StackConfig (Pydantic v2)
│       │   ├── generators.py #    Project scaffolding templates
│       │   └── version_config.py # Version-aware recommendations
│       ├── core/             # 🎯 Result types, compat, optimizations
│       │   ├── result.py     #    Ok / Err / safe
│       │   ├── compat.py     #    Python version feature flags
│       │   └── optimizations.py # uvloop / orjson bootstrap
│       ├── resilience/       # 🌊 Reliability patterns
│       │   ├── adaptive/          #    Orchestrators and Bulkheads
│       │   ├── watchdogs/         #    System health monitoring
│       │   ├── circuit_breaker.py #    Circuit breaker with on_state_change callback
│       │   └── retry.py           #    Exponential backoff with on_retry callback
│       ├── security/         # 🛡️ Guards, sanitizers, validators
│       │   ├── guards.py     #    Path traversal, command injection, env guards
│       │   ├── sanitizers.py #    XSS, filename, SQL, env value sanitization
│       │   ├── validators.py #    Email, URL, project name, Python version
│       │   └── decorators.py #    @safe_path, @safe_env wrappers
│       └── utils/            # 🔧 Cross-cutting utilities
│           ├── cache.py           #    Caching with @cached decorator
│           ├── logging.py         #    Structured logging (structlog)
│           ├── filesystem.py      #    Safe file operations
│           ├── rate_limit.py      #    Rate limiters
│           ├── concurrency.py     #    Async utilities
│           └── subprocess.py      #    Sandboxed subprocess execution
├── tests/                    # ✅ comprehensive test suite, 100% coverage
│   ├── test_property_sanitizers_expected.py # Hypothesis fuzzing
│   └── test_v034_async_retry_circuit.py # Async tests for retry and circuit breaker
├── docs/                     # 📖 MkDocs Material documentation
├── .semgrep/                 # 🔍 Custom SAST rules
├── .github/                  # 🔄 CI/CD + SBOM/SLSA + Docs workflows
├── Dockerfile                # 🐳 Hardened multi-stage container
└── pyproject.toml            # 📋 Modern dependency management (Poetry)

Concurrency Model¶

When production dependencies are installed (uvloop group), TaipanStack bootstraps uvloop as the asyncio event loop, providing a 2–4× throughput improvement over the standard asyncio loop on Linux/macOS.

from taipanstack.core.optimizations import apply_optimizations

apply_optimizations()  # Auto-installs uvloop + orjson if available

Python version detection is performed at import time via taipanstack.core.compat:

from taipanstack import PY313, get_features

if PY313:
    print(get_features())  # Reports 3.13-specific optimizations

Error Handling Philosophy¶

Exceptions represent unrecoverable panics. For standard, expected failures (network errors, validation failures, missing data), TaipanStack uses the Result monad:

Rule: Never raise to communicate a business failure

# ❌ DO NOT: leaks exception semantics into caller
def find_user(user_id: str) -> User:
    raise UserNotFoundError(...)

# ✅ DO: encode failure in the return type
def find_user(user_id: str) -> Result[User, UserNotFoundError]:
    return Err(UserNotFoundError(user_id))

Benefits enforced by Mypy strict:

You cannot forget to handle an Err — the type checker forces it
Pattern matching (match/case) gives exhaustive, safe unpacking
The @safe decorator wraps any raising function into a Result automatically

Security Strategy¶

TaipanStack's security layer is fail-closed by design:

Principle	Implementation
No silent failures	Malformed input raises `SecurityError` or `TypeError` immediately
Boundary validation	All external data validated at entry via `pydantic` + guards
Runtime type guards	Every public security function validates input types at v0.3.1+
AST scanning	Bandit + Semgrep (custom rules) runs on every CI push
Supply chain	SBOM (CycloneDX via Syft) + SLSA attestation (Cosign/Sigstore) on every release