SYSTEM 03

KULAI MODULES

REUSABLE PYTHON INFRASTRUCTURE

A 52-package first-party Python ecosystem covering application foundations, domain modules, persistence and FastAPI adapters.

PYTHONFASTAPIPYDANTICSQLALCHEMYREDISPOSTGRESQL

SYSTEM IDENTITY

SYSTEM IDKULAI-MODULES-03

STATUSACTIVE DEVELOPMENT

TYPESOFTWARE INFRASTRUCTURE

Reusable core, persistence and HTTP adapter layer for composing application systems.

01 / OVERVIEW

PROJECT OVERVIEW

KulAI Modules is a first-party Python package ecosystem for reusable application infrastructure and domain capabilities. It separates framework-neutral cores, persistence layers and FastAPI adapters so a new product can compose the pieces it needs.

The verified source snapshot contains 52 packages, 370 Python source files and 277 test files. The inventory covers configuration, logging, errors, databases, authentication, users, payments, subscriptions, access, jobs, providers and more.

02 / MODULE INVENTORY

COMPLETE MODULE MAP

MOD-01

kulai_auth

AUTHENTICATION CORE

Password hashing and HMAC JWT creation and validation without framework or persistence coupling.

MOD-02

kulai_auth_fastapi

FASTAPI AUTH

Email-password login, registration, refresh, logout and current-user dependency wiring.

MOD-03

kulai_balance

ECONOMIC CORE

Persistent wallets, reservations and append-only balance ledger with idempotent mutations.

MOD-04

kulai_balance_fastapi

FASTAPI ECONOMICS

Authenticated balance reads plus guarded user, internal and admin balance routes.

MOD-05

kulai_billing_access

ACCESS READ MODEL

Framework-neutral normalization of subscriptions, entitlements, balances and usage summaries.

MOD-06

kulai_billing_access_fastapi

FASTAPI ACCESS

Read-only billing access HTTP adapter with current-subject and guarded lookup routes.

MOD-07

kulai_billing_access_integrations

ACCESS INTEGRATION

Read-only adapters composing subscription, entitlement, balance and usage data.

MOD-08

kulai_cache

REDIS INFRASTRUCTURE

Async Redis client lifecycle, prefixed cache operations, JSON helpers and distributed locks.

MOD-09

kulai_calendar

CALENDAR CORE

Scoped services, resources, availability, bookings, lifecycle transitions and audit events.

MOD-10

kulai_calendar_fastapi

FASTAPI CALENDAR

HTTP schemas, dependency injection and configurable routes over the calendar core.

MOD-11

kulai_calendar_postgres

POSTGRES CONCURRENCY

PostgreSQL advisory locks for concurrency-sensitive booking creation and rescheduling.

MOD-12

kulai_cms

CONTENT ENGINE

Typed content, JSON-backed sections, navigation menus and contact-message persistence.

MOD-13

kulai_cms_admin_fastapi

CMS ADMIN UI

Server-rendered protected administration panel over the CMS admin API.

MOD-14

kulai_config

CONFIGURATION

Typed Pydantic settings, environment selection, layered dotenv loading and binding.

MOD-15

kulai_db

DATABASE FOUNDATION

Async SQLAlchemy engine and session infrastructure, ORM base and Alembic helpers.

MOD-16

kulai_devices

DEVICE IDENTITY

Guest and linked device records, secrets, device JWTs, linking, rotation and revocation.

MOD-17

kulai_devices_fastapi

FASTAPI DEVICES

FastAPI routes and dependency wiring for the device identity core.

MOD-18

kulai_errors

ERROR CONTRACT

Shared error codes, typed exceptions, public-detail separation and FastAPI handlers.

MOD-19

kulai_fastapi_core

FASTAPI FOUNDATION

Application factory, CORS setup, logging middleware and default exception registration.

MOD-20

kulai_fastapi_health

SERVICE HEALTH

Standard liveness and readiness endpoints with optional database checks.

MOD-21

kulai_logging

OBSERVABILITY

JSON logging and request or job correlation identifiers through context variables.

MOD-22

kulai_outbox

RELIABLE DISPATCH

Durable business events with leased, retryable and idempotent dispatch.

MOD-23

kulai_payments

PAYMENTS CORE

Normalized payment facts, Stripe signature verification, webhook claims and sanitization.

MOD-24

kulai_payments_balance

PAYMENT BRIDGE

Idempotent bridge from confirmed payment fulfillment requests to balance grants.

MOD-25

kulai_payments_fastapi

FASTAPI PAYMENTS

Signed Stripe webhook transport, database session wiring and fixed HTTP responses.

MOD-26

kulai_permissions

PERMISSION CORE

Framework-neutral deny-by-default permission evaluation with policies and ports.

MOD-27

kulai_permissions_db

PERMISSION STORAGE

Persistence and effective-policy loading for database-backed permission rules.

MOD-28

kulai_permissions_fastapi

FASTAPI PERMISSIONS

FastAPI adapter for core evaluation and database-backed permission policies.

MOD-29

kulai_plan_entitlements

PLAN DOMAIN

Portable contracts for feature access, usage limits and periodic credit grants.

MOD-30

kulai_plan_entitlements_db

PLAN STORAGE

Database definitions and lifecycle for plans, features, limits and credit grants.

MOD-31

kulai_plan_entitlements_fastapi

FASTAPI PLANS

HTTP access, guarded administration and read-only previews for plan entitlements.

MOD-32

kulai_plan_entitlements_integrations

PLAN INTEGRATION

Deterministic mapping from plan DTOs to permission, usage, balance and subscription data.

MOD-33

kulai_plans

PLAN CATALOG

Immutable price and duration catalog with database models and built-in seeding.

MOD-34

kulai_plans_fastapi

FASTAPI PLAN CATALOG

Public plan reads and guarded creation or default-seed actions.

MOD-35

kulai_provider_auth

PROVIDER AUTH CORE

Framework-neutral provider authentication use cases, contracts and profile handling.

MOD-36

kulai_provider_auth_fastapi

FASTAPI PROVIDER AUTH

HTTP validation, response mapping and composition around injected provider ports.

MOD-37

kulai_provider_auth_users_bridge

AUTH BRIDGE

Adapters connecting provider-auth flows with kulai_users and kulai_auth token issuance.

MOD-38

kulai_provider_facebook

FACEBOOK PROVIDER

Facebook Graph API token verification mapped to the provider profile contract.

MOD-39

kulai_provider_google

GOOGLE PROVIDER

Google ID token verification mapped to the provider profile contract.

MOD-40

kulai_provider_identities

IDENTITY STORAGE

Scoped external-provider identity mappings, profile snapshots and lifecycle services.

MOD-41

kulai_rate_limit

RATE LIMIT CORE

Weighted fixed-window rules, Redis counters, deterministic keys and limit errors.

MOD-42

kulai_rate_limit_fastapi

FASTAPI RATE LIMITING

Endpoint dependency, application middleware and proxy-aware client IP extraction.

MOD-43

kulai_sms_gateway

SMS CORE

Provider-neutral SMS dispatch, contracts, optional persistence and idempotent audit state.

MOD-44

kulai_sms_gateway_fastapi

FASTAPI SMS

HTTP-safe SMS send and audit-read routes with dependency wiring.

MOD-45

kulai_subscriptions

SUBSCRIPTION DOMAIN

Provider-neutral lifecycle functions for start, cancellation, payment changes and access.

MOD-46

kulai_subscriptions_db

SUBSCRIPTION STORAGE

Durable subscription facts, period processing, outbox requests and balance handlers.

MOD-47

kulai_subscriptions_fastapi

FASTAPI SUBSCRIPTIONS

Subject reads, guarded administration and internal period-grant preparation routes.

MOD-48

kulai_tasks

ASYNC JOBS

Redis-backed enqueue, workers, retries, dead-letter routing and interval scheduling.

MOD-49

kulai_tunnels

SERVICE TUNNELS

Provider abstraction and lifecycle management for exposing a local HTTP service.

MOD-50

kulai_usage

USAGE TRACKING

Scoped daily counters, quota checks and read-only usage projections.

MOD-51

kulai_users

USER PERSISTENCE

User accounts, password authentication and refresh-token revocation persistence.

MOD-52

kulai_users_fastapi

FASTAPI USERS

Authenticated self-service account reads and email updates.

03 / CORE INFRASTRUCTURE

FOUNDATION LAYER

FOUND-01

KULAI_CONFIG

Typed settings and dotenv loading give applications a shared configuration contract without owning an external service.

FOUND-02

KULAI_LOGGING

JSON formatting and request or job correlation make logs consistent across HTTP services, workers and CLI processes.

FOUND-03

KULAI_ERRORS

A common error taxonomy separates safe public payloads from internal details and provides reusable handlers.

FOUND-04

KULAI_DB

Async SQLAlchemy engine, sessions, ORM foundations and migration helpers establish the persistence boundary.

FOUND-05

KULAI_AUTH

Password and JWT primitives remain framework-independent, while user lookup and persistence stay in composing packages.

FOUND-06

KULAI_FASTAPI_CORE

Application factories, CORS, middleware and default exception registration form a reusable HTTP assembly layer.

04 / COMPOSITION MODEL

HOW MODULES WORK TOGETHER

The source establishes a repeatable composition path: the host supplies configuration and application policy, core modules own focused rules, persistence packages own storage, and FastAPI packages translate those capabilities into HTTP boundaries.

Host application composition path

HOST APPLICATION
KULAI_CONFIG
KULAI_DB
DOMAIN / SERVICE

FASTAPI ADAPTER
HTTP ROUTE

05 / PRACTICAL REUSE

PROJECT BOOTSTRAP / INTEGRATION

UC-01

BOOTSTRAP A SERVICE

Start with typed configuration, shared logging, error handling and database session infrastructure instead of recreating those boundaries in every application.

UC-02

ADD A DOMAIN CAPABILITY

Select a focused core such as calendar, subscriptions, CMS, users or payments and keep its use cases behind an explicit package API.

UC-03

EXPOSE HTTP ROUTES

Add the matching FastAPI adapter when an application needs route factories, request schemas and injected host dependencies.

UC-04

COMPOSE CROSS-CUTTING FLOWS

Combine access, entitlements, balance, usage, outbox, cache and task modules where the application actually needs those capabilities.

UC-05

KEEP HOST OWNERSHIP CLEAR

Let the host application provide its transaction boundary, policy decisions, external credentials and application-specific workflows.

06 / ENGINEERING DECISIONS

ARCHITECTURE IN THE SOURCE

ENG-01

EXPLICIT PACKAGE BOUNDARIES

Core domain packages, persistence packages and FastAPI adapters are split into separate distributions with documented responsibility boundaries.

ENG-02

HOST-OWNED TRANSACTIONS

Many repository and service layers flush and refresh without committing, leaving the outer transaction to the host or HTTP adapter where documented.

ENG-03

STABLE PUBLIC APIS

Package roots define exported models, factories and use cases so consuming applications have deliberate integration points.

ENG-04

READ-ONLY INTEGRATION PORTS

Billing access integrations compose existing persistence modules through read ports without mutating subscriptions, balances or usage.

ENG-05

DATABASE DISCOVERY WITHOUT MIGRATION OWNERSHIP

ORM registration exposes models to host Alembic autogeneration while schema revision ownership remains explicit.

ENG-06

RELIABILITY AS MODULES

Idempotency, outbox dispatch, retries, leases, revocation and advisory locks appear as focused responsibilities rather than hidden application code.

07 / TECHNICAL INVENTORY

VERIFIED STACK

STACK-01

PYTHON

All 52 first-party packages are Python distributions with source under their package src directories.

STACK-02

FASTAPI

Dedicated adapter packages provide configurable routers, dependencies and application factories.

STACK-03

PYDANTIC

Settings, domain objects and HTTP schemas use typed validation boundaries across the ecosystem.

STACK-04

SQLALCHEMY

Database-backed packages use async ORM models, repositories, sessions and shared metadata conventions.

STACK-05

ALEMBIC

Migration revisions and model-registration helpers are present in persistence packages and host integration paths.

STACK-06

REDIS

Cache, rate-limit and task modules use Redis for shared counters, locks, queues and durable runtime state.

STACK-07

POSTGRESQL

The source includes PostgreSQL persistence paths and a dedicated advisory-lock adapter for calendar concurrency.

STACK-08

STRIPE / NGROK ADAPTERS

Payment webhook and local tunnel packages isolate provider-specific boundaries behind focused adapters.

08 / PROJECT STATE

CURRENT SCOPE

STATE ACTIVE DEVELOPMENT

MODULES 52 FIRST-PARTY PACKAGES

SOURCE 370 PYTHON SOURCE FILES

TESTS 277 TEST FILES / 1724 TEST FUNCTIONS

PRIMARY ROLE REUSABLE CORE / PERSISTENCE / FASTAPI ADAPTERS