Optional Modules & Feature Flags

craft-easy-api ships with all optional modules disabled by default. Each module is activated by a single environment variable. Unused modules never register their routes, initialize their Beanie document models, or import their dependencies — keeping startup time and memory footprint proportional to what the application actually uses.

Module Reference

Module	Flag	Default	Activates
Tags	TAGS_ENABLED	false	Tag document model; /tags CRUD endpoints
Finance	FINANCE_ENABLED	false	Cost types, payment accounts, client funds, claims, collections, revenue splits, settlements; see Financial
Payments	PAYMENTS_ENABLED	false	Payment and PayoutBatch models; payments, payouts, bank matching, and reconciliation endpoints — requires FINANCE_ENABLED
Bookkeeping	BOOKKEEPING_ENABLED	false	LedgerEntry and Invoice models; ledger, invoice, and bookkeeping endpoints — requires FINANCE_ENABLED
Notifications	NOTIFICATIONS_ENABLED	false	NotificationTemplate and NotificationLog models; /notification-templates endpoints; seeds default templates on startup
ERD	ERD_ENABLED	false	/erd schema introspection endpoint (returns a machine-readable entity-relationship graph)
Jobs	JOBS_ENABLED	false	JobRun and JobSchedule models; /jobs endpoints; registers all built-in background jobs on startup
File Import	FILE_IMPORT_ENABLED	false	Import sources, templates, runs, rejected records, SLA monitoring, alert channels, routing rules, holiday calendars, batch insert; seeds built-in holiday calendars; registers SLA monitor job
Archive	ARCHIVE_ENABLED	false	RetentionPolicy and GDPRPurgeRecord models; archive, retention-policy, and GDPR-import endpoints; registers retention cleanup job — requires JOBS_ENABLED for scheduled cleanup
GDPR	GDPR_ENABLED	false	GDPR erasure and data-export endpoints; see GDPR
BI Export	BI_EXPORT_ENABLED	false	/bi-export endpoints for pushing data to BigQuery or Azure SQL; see BI Export
White Label	WHITE_LABEL_ENABLED	false	Tenant-specific custom-domain routing (domain → tenant slug resolution at the middleware layer)
Webhooks	WEBHOOKS_ENABLED	false	WebhookEvent model; webhook receiver and admin endpoints; see Webhooks

Reducing Startup Time and Dependencies

Every module that stays disabled never touches its document models or routes. This has several concrete benefits:

Fewer MongoDB collections — Beanie only initialises document models that are included in build_models(). Disabled modules do not create collections or indexes.

Smaller import graph — Route modules are imported lazily inside if settings.<FLAG>_ENABLED: blocks in create_app(). A deployment that never enables BI_EXPORT_ENABLED never imports the BI export router or its transitive dependencies.

Shorter build_models() list — The _init_database startup step calls init_beanie() only with the active model set. Each additional model adds an index-verification round-trip against MongoDB; disabling unused modules reduces this overhead linearly.

To keep a deployment lean, enable only the modules your application actually uses:

# Minimal deployment: authentication + tenancy only (all optional modules off)
AUTH_ENABLED=true
MULTI_TENANT_ENABLED=true

# Add financial features
FINANCE_ENABLED=true
PAYMENTS_ENABLED=true

# Add background jobs
JOBS_ENABLED=true

Module Dependencies and Combinations

Some modules build on others. The validator in Settings enforces hard dependencies at startup and raises a ValueError before the application accepts traffic.

Finance sub-modules

PAYMENTS_ENABLED and BOOKKEEPING_ENABLED both require FINANCE_ENABLED. Enabling either without the parent module raises:

ValueError: PAYMENTS_ENABLED=True requires FINANCE_ENABLED=True
ValueError: BOOKKEEPING_ENABLED=True requires FINANCE_ENABLED=True

Typical configurations:

# Finance only (no payments, no bookkeeping)
FINANCE_ENABLED=true

# Finance with payment processing
FINANCE_ENABLED=true
PAYMENTS_ENABLED=true

# Full financial stack
FINANCE_ENABLED=true
PAYMENTS_ENABLED=true
BOOKKEEPING_ENABLED=true

Archive and Jobs

ARCHIVE_ENABLED registers a retention_cleanup job, but the job only runs if JOBS_ENABLED is also set. Without Jobs, the retention-policy routes and models are available for manual API calls, but automatic scheduled cleanup does not execute.

# Archive with automatic cleanup
ARCHIVE_ENABLED=true
JOBS_ENABLED=true

# Archive without scheduled cleanup (manual API only)
ARCHIVE_ENABLED=true

File Import and Archive

FILE_IMPORT_ENABLED activates the import engine independently of ARCHIVE_ENABLED. Enable both when you need long-term archival of raw import files alongside the import metadata:

FILE_IMPORT_ENABLED=true
ARCHIVE_ENABLED=true
JOBS_ENABLED=true  # Enables SLA monitor + retention cleanup jobs

Notifications

NOTIFICATIONS_ENABLED controls the notification-template management API and the NotificationLog document. It is independent of the outbound delivery settings (MAIL_PROVIDER, SENDGRID_*, ELKS_*, FCM_*). You can run the delivery infrastructure without storing templates in the database, or enable templates without configuring a live delivery provider (useful for dry-run environments where NOTIFICATION_DRY_RUN=true).

Common Deployment Profiles

Minimal — auth and tenancy only

AUTH_ENABLED=true
MULTI_TENANT_ENABLED=true
# All optional modules remain false (default)

SaaS platform

FINANCE_ENABLED=true
PAYMENTS_ENABLED=true
NOTIFICATIONS_ENABLED=true
WEBHOOKS_ENABLED=true
GDPR_ENABLED=true
JOBS_ENABLED=true

Data-ingestion pipeline

FILE_IMPORT_ENABLED=true
ARCHIVE_ENABLED=true
JOBS_ENABLED=true
BI_EXPORT_ENABLED=true

Internal tooling / backoffice

TAGS_ENABLED=true
NOTIFICATIONS_ENABLED=true
ERD_ENABLED=true
JOBS_ENABLED=true

See Also

• Settings Reference — complete list of all configuration variables including per-module tuning knobs (FILE_IMPORT_MAX_SIZE_MB, JOBS_CLEANUP_DAYS, etc.)
• Financial Overview
• File Import Engine
• Job Framework
• Webhooks