# Docs

- [Quick Start](/docs/quick-start): From pip install to running API in 60 seconds. Add ZCore pieces only where they help.
- [What is ZCore?](/docs/what-is-zcore): A modular architectural framework designed for FastAPI by Baseryn. Use an isolated component or adopt the full stack — your code stays standard FastAPI.
- [Comparisons](/docs/comparisons): Honest architectural comparisons with plain FastAPI, Django, and other tools. ZCore is not a replacement — it is a composable alternative.
- Quick learn
  - [Step 1 - Installation & Environment](/docs/quick-learn/step-1): Install ZCore properly and configure your environment variables securely using the built-in CLI.
  - [Step 2 - Database Engine Setup](/docs/quick-learn/step-2): Configure the asynchronous SQLAlchemy engine and understand how ZCore handles connection pooling and query logging.
  - [Step 3 - Scaffolding Domain Modules](/docs/quick-learn/step-3): Use the ZCore CLI to generate a structured, decoupled domain module for your tasks.
  - [Step 4 - Defining Models & Permissions](/docs/quick-learn/step-4): Create standard SQLAlchemy 2.0 models and learn how ZCore auto-generates permission keys.
  - [Step 5 - Schemas & Dynamic Security (Zchema)](/docs/quick-learn/step-5): Define Pydantic schemas and use Zchema to automatically mask sensitive fields based on user context.
  - [Step 6 - Data Access Layer (BaseRepository)](/docs/quick-learn/step-6): Implement asynchronous CRUD, keyset pagination, and secure search out of the box with zero boilerplate.
  - [Step 7 - Business Logic Layer (BaseService & DI)](/docs/quick-learn/step-7): Isolate business rules using lifecycle hooks and automatic dependency injection.
  - [Step 8 - Web Layer & Plugin System](/docs/quick-learn/step-8): Scaffold 8 secure endpoints instantly and register your domain with the application Kernel.
  - [Step 9 - Security & Context (Auth & Scopes)](/docs/quick-learn/step-9): Implement JWT authentication and bind user scopes to the ZContext for dynamic field pruning.
  - [Step 10 - Testing & Expected Output](/docs/quick-learn/step-10): Write isolated tests using ZTestClient with automatic database rollback and user mocking.
- How to
  - [How to extend the Settings class](/docs/how-to/extend-settings): Add custom environment variables to your ZCore application securely.
  - [How to configure Database and Logging](/docs/how-to/configure-database-and-logging): Configure asynchronous database engines with DatabaseSettings and customize structured logging with LoggingSettings and file rotation.
  - [How to manage Timezones and DateTime serialization](/docs/how-to/manage-timezones): Configure application-wide timezones, convert datetimes, and serialize timezone-aware outputs using ZDateTime.
  - [How to use CLI commands](/docs/how-to/use-cli-commands): Master the ZCore interactive CLI for project scaffolding, domain app generation, environment management, and advanced server orchestration.
  - [How to wire dependencies with Inject\[T\]](/docs/how-to/wire-dependencies): Connect services, repositories, and external clients automatically using IoC and Annotated injection.
  - [How to register Singleton vs Scoped services](/docs/how-to/register-singleton-vs-scoped): Understand when to use global singletons, request-scoped instances, and transient dependencies.
  - [How to run isolated background tasks](/docs/how-to/run-background-tasks): Execute async background jobs, auto-wire services, and isolate database sessions without HTTP request lifecycle leaks.
  - [How to override BaseRepository methods](/docs/how-to/override-repository): Add custom persistence logic, override CRUD operations, or execute raw SQLAlchemy queries in the repository layer.
  - [How to extend BaseRouter with Custom Reusable Endpoints](/docs/how-to/extend-base-router): Build a shared AppBaseRouter to add reusable custom endpoints (such as bulk status updates or CSV export) across all your domain routers.
  - [How to structure inter-module contracts and dependency wiring](/docs/how-to/inter-module-contracts-and-wiring): Decouple domain modules using Python Protocols, shared contracts, DI container wiring, and explicit Upstream/Downstream boundaries.
  - [How to enforce multi-tenancy & soft deletion](/docs/how-to/use-scope-query): Automatically isolate tenant data and filter soft-deleted records across all repository queries using SoftDeleteMixin and scope_query.
  - [How to implement Cursor Pagination](/docs/how-to/implement-cursor-pagination): High-performance keyset pagination for large datasets and real-time feeds without offset drift.
  - [How to build complex search queries](/docs/how-to/build-complex-search): Construct nested AND/OR/NOT filters, eager-load relations, use inverted/range operators, and execute secure dynamic searches.
  - [How to use pre/post hooks in Services](/docs/how-to/use-pre-post-hooks): Execute business logic, compute fields, coordinate side-effects, and handle soft-delete restoration across mutation lifecycles.
  - [How to use UnitOfWork for atomic transactions](/docs/how-to/use-unit-of-work): Coordinate multi-repository writes and post-commit domain events within an atomic all-or-nothing boundary.
  - [How to listen to and dispatch domain events](/docs/how-to/listen-to-events): Subscribe to event channels using @on_event decorators, register listeners in plugins, and dispatch events safely.
  - [How to handle and raise domain exceptions](/docs/how-to/handle-custom-exceptions): Raise built-in domain exceptions, create custom business errors, and return standardized JSON error envelopes.
  - [How to mask sensitive fields dynamically](/docs/how-to/mask-sensitive-fields): Use Zchema to automatically prune fields from API responses, sanitize inputs, and mask OpenAPI schemas.
  - [How to expose dynamic schemas (?schema=true)](/docs/how-to/expose-dynamic-schemas): Generate frontend form schemas automatically with contextual, role-based field pruning.
  - [How to enforce Permission Scopes](/docs/how-to/enforce-permission-scopes): Secure endpoints using automated model action scopes, custom route dependencies, and HasScopes.
  - [How to securely upload files](/docs/how-to/upload-files-securely): Store files safely using Magic Byte inspection, file size guards, and path traversal defenses.
  - [How to cache database queries](/docs/how-to/cache-database-queries): Accelerate queries using BaseCache with automatic Pydantic deserialization, tunable settings, and resilient local LRU fallback.
  - [How to test API endpoints](/docs/how-to/test-endpoints): Write isolated, lightning-fast integration tests using ZTestClient with automatic database rollback and user mocking.
  - [How to mock authenticated users in tests](/docs/how-to/mock-users-in-tests): Simulate different user roles, scopes, superusers, and context restrictions without JWT overhead.
- Core concepts
  - [Configuration & Context Management](/docs/core-concepts/context): Deep dive into how ZCore handles application settings via lazy proxies and isolates request-scoped state using contextvars.
  - [Dependency Injection (IoC Container)](/docs/core-concepts/di): Explore ZCore's custom Inversion of Control container, constructor auto-wiring, signature caching, and lifecycle management.
  - [Kernel & Plugin Orchestration](/docs/core-concepts/kernel): Understand how ZCore orchestrates application modularity, topological startup ordering, and deterministic lifespans.
  - [Dynamic Search Engine & Security](/docs/core-concepts/search): How ZCore compiles nested JSON filters into safe SQL, protects against DoS attacks, and enforces column-level security.
  - [Unit of Work & Deferred Events](/docs/core-concepts/uow): Deep dive into atomic transaction boundaries and why domain events must be decoupled from database commits.
  - [Zchema & Context Shielding](/docs/core-concepts/zchema): Understand how ZCore intercepts Pydantic V2 to provide dynamic, role-based field pruning across validation, serialization, and OpenAPI schema generation.
  - [Security & Authentication Architecture](/docs/core-concepts/security): Explore ZCore's cryptographic services (Argon2id, JWT), the BaseAuth template pipeline, fail-fast production assertions, and scope permissions.
  - [Caching & Real-Time Streaming](/docs/core-concepts/cache-and-streams): Deep dive into ZCore's distributed Redis cache with resilient in-memory LRU fallback and the cluster-wide PubSub streaming engine.
  - [Testing Infrastructure (ZTestClient)](/docs/core-concepts/testing): Explore how ZCore orchestrates IoC sandboxes, savepoint database rollbacks, context mocking, and application lifespans.
  - [File Storage Security Architecture](/docs/core-concepts/storage): Deep dive into how ZCore prevents path traversal, DoS through large files, arbitrary file deletions, and executable MIME spoofing.
  - [CLI & Structured Logging](/docs/core-concepts/cli-and-logging): Deep dive into ZCore's cascading server runner, introspection-based environment scaffolding, and unified structlog observability pipeline.
- Api reference
  - [BaseRepository](/docs/api-reference/repository): Comprehensive API reference for the BaseRepository class, query scoping, bulk operations, soft-delete lifecycles, and restoration methods.
  - [SearchEngine](/docs/api-reference/search): API reference for the dynamic search engine, query builders, filter operators, inverted comparisons, and configurable relation depth.
  - [BaseService](/docs/api-reference/service): Complete API reference for the BaseService class, CRUD orchestration, restoration methods, execution delegators, and single/bulk lifecycle hooks.
  - [UnitOfWork](/docs/api-reference/uow): API reference for the UnitOfWork class managing atomic transactions, lifecycle boundaries, and deferred domain events.
  - [BaseRouter](/docs/api-reference/base-router): Comprehensive API reference for the BaseRouter class, RouteKey enumeration, lookup projections, and endpoint overrides.
  - [ZCoreAPIRoute & Web Adapters](/docs/api-reference/api-router): API reference for ZCoreAPIRoute, request body caching, and dynamic OpenAPI schema interceptors.
  - [Zchema (Schema Projection)](/docs/api-reference/zchema): API reference for the Zchema base class used for dynamic, role-based field pruning and context shielding.
  - [ResponseWrapper](/docs/api-reference/response-wrapper): API reference for the generic JSON API response envelope and serialization container.
  - [Exceptions & Centralized Error Handling](/docs/api-reference/exceptions): API reference for ZCore's domain exception hierarchy, HTTP status code mappings, sanitization helpers, and unified handler registration.
  - [IoC Container & Dependency Injection](/docs/api-reference/ioc-container): API reference for ZCore's Inversion of Control container, lifecycle registration methods, and Inject type marker.
  - [Inject & Injector](/docs/api-reference/inject): API reference for the dynamic Annotated type marker bridging FastAPI route parameters with the IoC container.
  - [EventDispatcher & @on_event](/docs/api-reference/events): API reference for EventDispatcher, the @on_event listener decorator, and dynamic IoC-backed subscriber registration.
  - [Background Tasks & Scopes](/docs/api-reference/background-tasks): API reference for background_scope and @background_task decorator for isolated asynchronous execution.
  - [Security Services](/docs/api-reference/security): API reference for the Security class providing Argon2id password hashing, JWT lifecycle, and cryptographic utilities.
  - [BaseAuth](/docs/api-reference/base-auth): API reference for the generic BaseAuth authentication template, dynamic cache TTL, and context binding pipeline.
  - [BaseCache & Caching Layer](/docs/api-reference/base-cache): API reference for BaseCache with Redis integration, Pydantic deserialization, tunable defaults, and in-memory TTLLRUCache fallback.
  - [StreamManager](/docs/api-reference/stream-manager): API reference for the real-time event streaming engine using Redis PubSub, tunable queue limits, and bounded memory queues.
  - [LocalStorageProvider](/docs/api-reference/local-storage-provider): API reference for LocalStorageProvider with path traversal defense, stream uploading, and validation guards.
  - [Storage Validators](/docs/api-reference/storage-validators): API reference for file upload security validators including Magic Byte inspection, DoS size limits, and extension whitelisting.
  - [ZContext](/docs/api-reference/zcontext): API reference for the asynchronous, thread-safe request context manager and state isolation engine.
  - [Settings & Configuration](/docs/api-reference/settings): API reference for the Pydantic V2 Settings module, SettingsProxy lazy loader, framework boundaries, and environment initializers.
  - [Kernel & Plugin Architecture](/docs/api-reference/kernel): API reference for the central Kernel orchestrator, topological dependency resolver, and Plugin lifecycle protocol.
  - [Plugin Protocol](/docs/api-reference/plugin): API reference for the runtime-checkable Plugin protocol defining modular application lifecycles.
  - [Utilities & Helpers](/docs/api-reference/utilities): API reference for JSON serialization, dynamic timezone management, Draft-7 schema validation, text slugification, and database event bridges.
  - [ZTestClient & BaseZTest](/docs/api-reference/ztest-client): API reference for ZTestClient and BaseZTest providing zero-boilerplate async integration testing and transaction isolation.
  - [Testing Fixtures & Orchestrator](/docs/api-reference/testing-fixtures): API reference for ZCore's composable testing fixtures managing IoC sandboxing, database rollbacks, context mocking, and lifespans.
- [Changelog & Release Notes](/docs/changelog): Track the evolution, architectural refinements, breaking changes, and security fixes across ZCore Framework releases.