nullchemy

Executive Summary

nullchemy is a microservice platform composed of seven independent services — auth-service, user-service, notifications-service, documents-service, inventory-service, analytics-service, and audit-service — all built upon a shared pip-installable core package named tq-core. The system is designed for horizontal scalability on Kubernetes, with asynchronous inter-service communication, strict data ownership boundaries, and a unified authentication layer at the API gateway.

The architecture follows a shared-nothing principle: each service owns its database, no two services share a schema, and all cross-service data flow happens through well-defined APIs or asynchronous message channels. The core package tq-core eliminates duplication by providing JWT authentication, database session factories, base ORM models, Pydantic schemas, middleware, and structured logging — every service installs it as a versioned dependency.

Key quantitative targets and design principles:

• Peak throughput: 10,000 requests per second across the API gateway, with each service individually capable of 1,000–3,000 RPS depending on its I/O profile.
• Latency budget: p95 < 100ms for all read endpoints; p95 < 500ms for write endpoints that involve cross-service async communication.
• Availability: 99.9% uptime SLA (approximately 8.76 hours of downtime per year), enforced via Kubernetes auto-scaling, pod anti-affinity, and multi-zone deployment.
• Data consistency: Strong consistency within each service boundary; eventual consistency across services via the message broker (RabbitMQ), with a maximum staleness window of 5 seconds.
• Security posture: JWT-based authentication at the gateway, TLS everywhere, network policies isolating service-to-service traffic, and a dedicated audit trail across all mutating operations.

Architecture Overview

The global architecture follows a gateway-perimeter pattern: all external traffic enters through Kong API Gateway, which handles JWT validation, rate limiting, and request routing before forwarding to the appropriate microservice. Services communicate with each other through a RabbitMQ message broker for asynchronous operations, and directly via HTTP for synchronous reads that require immediate consistency.

graph TD
    Client["Client (Web/Mobile/CLI)"]
    APIG["API Gateway (Kong)"]
    AuthSvc["auth-service"]
    UserSvc["user-service"]
    NotifSvc["notifications-service"]
    DocSvc["documents-service"]
    InvSvc["inventory-service"]
    AnalytSvc["analytics-service"]
    AuditSvc["audit-service"]
    CorePkg["tq-core (Shared Package)"]
    DB[(PostgreSQL Cluster)]
    Cache[(Redis Cache)]
    MQ{{"Message Broker (RabbitMQ)"}}

    Client -->|HTTPS| APIG
    APIG -->|JWT Auth| AuthSvc
    APIG -->|Route| UserSvc
    APIG -->|Route| NotifSvc
    APIG -->|Route| DocSvc
    APIG -->|Route| InvSvc
    APIG -->|Route| AnalytSvc
    APIG -->|Route| AuditSvc
    AuthSvc -->|import| CorePkg
    UserSvc -->|import| CorePkg
    NotifSvc -->|import| CorePkg
    DocSvc -->|import| CorePkg
    InvSvc -->|import| CorePkg
    AnalytSvc -->|import| CorePkg
    AuditSvc -->|import| CorePkg
    AuthSvc --> DB
    UserSvc --> DB
    NotifSvc --> DB
    DocSvc --> DB
    InvSvc --> DB
    AnalytSvc --> DB
    AuditSvc --> DB
    AuthSvc --> Cache
    UserSvc --> Cache
    NotifSvc --> Cache
    MQ --> AuthSvc
    MQ --> UserSvc
    MQ --> NotifSvc
    MQ --> DocSvc
    MQ --> InvSvc
    MQ --> AnalytSvc
    MQ --> AuditSvc
    AuthSvc --> MQ
    UserSvc --> MQ
    NotifSvc --> MQ
    DocSvc --> MQ
    InvSvc --> MQ
    AnalytSvc --> MQ
    AuditSvc --> MQ
                        

Core Package: tq-core

tq-core is the shared Python package installed by every nullchemy microservice. It is versioned, published to a private PyPI registry, and pinned in each service's pyproject.toml. The package eliminates code duplication across seven services, ensures consistent behavior for cross-cutting concerns, and provides a single source of truth for authentication, database access, and schema definitions.

Package Structure

The following table lists every module exposed by tq-core. Each module is imported by at least five of the seven services.

auth-service

Role: The identity provider for the entire platform. Handles user registration, login, token issuance and refresh, password management, and multi-factor authentication (MFA). It is the only service that stores password hashes and issues JWTs.

Database strategy: Owns the auth schema within the shared PostgreSQL cluster. Tables: users (core identity), sessions (active refresh tokens), mfa_devices, password_reset_tokens. No other service reads from this schema directly — all identity lookups go through the auth-service API or the validated JWT claims.

Key API Endpoints

Entity Schema: users (auth schema)

Dependencies: tq-core (auth, db, exceptions, logging), notifications-service (async — for sending welcome emails, password reset emails via RabbitMQ), audit-service (async — all login/logout events are published to the audit queue).

user-service

Role: Manages user profiles, preferences, and account-level settings. This service owns the extended user data — everything about a user that is not authentication-related: display names, avatars, contact details, notification preferences, and account metadata.

Database strategy: Owns the users schema. Tables: profiles (1:1 with auth.users via auth_user_id FK reference — logical, not enforced by DB constraint since tables reside in different schemas), preferences, avatars. The user-service never stores passwords or handles authentication directly.

Key API Endpoints

Dependencies: tq-core (auth, db, schemas, exceptions, logging, cache), auth-service (sync HTTP — validates user existence on profile creation), documents-service (sync HTTP — avatar uploads), audit-service (async — profile changes are audited).

notifications-service

Role: Centralized notification delivery engine. Handles email (SMTP + SendGrid), SMS (Twilio), and push notifications (Firebase Cloud Messaging). Other services publish notification requests to a RabbitMQ queue; this service consumes them, renders templates, and dispatches to the appropriate channel.

Database strategy: Owns the notifications schema. Tables: templates (Jinja2 templates stored in DB for runtime editing), messages (outbox of all sent notifications with status tracking), delivery_logs (per-channel delivery status with timestamps), preferences (per-user channel opt-in/opt-out).

Key API Endpoints

Dependencies: tq-core (auth, db, messaging, logging), RabbitMQ (consumes notification requests from all other services), external providers (SendGrid, Twilio, Firebase).

documents-service

Role: Document storage, retrieval, versioning, and metadata management. Supports upload of any file type with content-type validation, generates thumbnails for images, and provides signed URLs for secure downloads. Integrates with object storage (S3-compatible) for binary data.

Database strategy: Owns the documents schema. Tables: documents (metadata — filename, MIME type, size, S3 key, version chain), document_versions (version history with content hashes), tags, document_tags (many-to-many). Binary data is stored in S3/MinIO, not in PostgreSQL.

Key API Endpoints

Dependencies: tq-core (auth, db, exceptions, logging), S3-compatible object storage (MinIO in development, AWS S3 in production), audit-service (async — document access and version changes).

inventory-service

Role: Manages stock items, categories, warehouses, and inventory movements. Tracks quantities across multiple locations, handles stock reservations, and emits low-stock alerts. Designed for eventual consistency with the analytics-service for real-time inventory dashboards.

Database strategy: Owns the inventory schema. Tables: items (SKU, name, description, unit), categories (hierarchical), warehouses (locations), stock_levels (item + warehouse + quantity with optimistic locking), movements (audit trail of all stock changes — inbound, outbound, transfer, adjustment).

Key API Endpoints

Dependencies: tq-core (auth, db, schemas, cache, messaging, logging), notifications-service (async — low-stock alerts via RabbitMQ), analytics-service (async — stock movement events for dashboard aggregation), audit-service (async — all movements).

analytics-service

Role: Event ingestion, metrics aggregation, and reporting. Consumes events from a dedicated Kafka topic (high-throughput event stream) and RabbitMQ (lower-throughput operational events). Provides aggregated dashboards, time-series queries, and CSV/PDF report generation.

Database strategy: Uses a time-series optimized schema separate from the standard tq-core base model. Tables in the analytics schema: events_raw (append-only event log, partitioned by month), metrics_hourly (pre-aggregated hourly rollups), metrics_daily (daily rollups), reports (scheduled report definitions). Also queries a read replica of the inventory schema for real-time stock analytics.

Key API Endpoints

Dependencies: tq-core (config, auth, logging, schemas), Kafka (primary event ingestion), RabbitMQ (operational events from other services), PostgreSQL with partitioning support.

audit-service

Role: Immutable audit trail for all mutating operations across the platform. Consumes audit events from a dedicated RabbitMQ queue, writes them to an append-only table, and provides query APIs for compliance and investigation. Designed for write-once, read-infrequently access patterns.

Database strategy: Owns the audit schema. Primary table: audit_log — append-only, partitioned by month, with BRIN indexes on timestamp. Columns: event_id, timestamp, service_name, user_id, action, resource_type, resource_id, old_values (JSONB), new_values (JSONB), ip_address, user_agent, correlation_id. No UPDATE or DELETE operations are ever performed on this table.

Key API Endpoints

Dependencies: tq-core (auth, db, messaging, logging), RabbitMQ (consumes audit events from all services). This service has zero outbound dependencies — it never calls another service.

Authentication & Authorization Flow

The authentication flow begins at the API gateway and propagates through every service via signed JWTs. The gateway validates the token on every request (using the shared secret from tq-core), extracts the user identity and role, and forwards them as headers to downstream services. This eliminates the need for each service to call auth-service on every request.

sequenceDiagram
    participant C as Client
    participant G as API Gateway (Kong)
    participant A as auth-service
    participant Core as tq-core (Shared)
    participant T as Target Service
    participant Audit as audit-service

    C->>G: POST /login (email + password)
    G->>A: Forward login request
    A->>Core: verify_password(plain, hash)
    Core-->>A: password valid
    A->>Core: create_access_token(user_data)
    Core-->>A: signed JWT
    A->>Core: create_refresh_token(user_data)
    Core-->>A: signed refresh token
    A->>Audit: Publish login event (async via RabbitMQ)
    A-->>G: access + refresh tokens
    G-->>C: tokens (HTTPOnly cookies)

    Note over C,T: All subsequent API calls

    C->>G: GET /users/me (Bearer token)
    G->>G: Validate JWT signature via tq-core
    G->>T: Proxy request + X-User-ID + X-User-Role headers
    T->>Core: get_current_user(headers)
    Core-->>T: UserData object
    T->>T: Authorize based on role
    T-->>G: Response
    G-->>C: JSON payload
                        

Inter-Service Communication

nullchemy uses a hybrid communication model: synchronous HTTP for reads that require immediate consistency, and asynchronous messaging via RabbitMQ for operations that can tolerate eventual consistency or have high latency.

graph LR
    subgraph Sync["Synchronous (HTTP)"]
        US["user-service"] -->|"GET /verify-user"| AS["auth-service"]
        DS["documents-service"] -->|"GET /users/{id}"| US
        IS["inventory-service"] -->|"GET /documents/{id}"| DS
    end

    subgraph Async["Asynchronous (RabbitMQ)"]
        AS2["auth-service"] -->|"user.registered"| NS["notifications-service"]
        IS2["inventory-service"] -->|"stock.low"| NS
        IS2 -->|"stock.changed"| AN["analytics-service"]
        US2["user-service"] -->|"profile.updated"| AU["audit-service"]
        AS2 -->|"user.login"| AU
        DS2["documents-service"] -->|"document.accessed"| AU
    end
                        

Data Flow & Storage

Each service owns its data domain exclusively. No service directly accesses another service's database — all cross-domain data access happens through APIs. This enforces strong encapsulation and allows each service to evolve its schema independently.

graph TD
    subgraph PostgreSQL["PostgreSQL Cluster"]
        subgraph SchemaAuth["auth schema"]
            AuthUsers["users"]
            AuthSessions["sessions"]
        end
        subgraph SchemaUsers["users schema"]
            UserProfiles["profiles"]
            UserPrefs["preferences"]
        end
        subgraph SchemaNotif["notifications schema"]
            NotifTemplates["templates"]
            NotifMessages["messages"]
        end
        subgraph SchemaDocs["documents schema"]
            DocsMeta["documents"]
            DocsVersions["document_versions"]
        end
        subgraph SchemaInv["inventory schema"]
            InvItems["items"]
            InvStock["stock_levels"]
            InvMovements["movements"]
        end
        subgraph SchemaAnalyt["analytics schema"]
            AnalytEvents["events_raw"]
            AnalytMetrics["metrics_hourly"]
        end
        subgraph SchemaAudit["audit schema"]
            AuditLog["audit_log"]
        end
    end

    S3["S3/MinIO (Binary Storage)"]
    Redis["Redis (Cache & Sessions)"]
    Kafka["Kafka (Event Stream)"]

    DocsMeta -->|"S3 key reference"| S3
    AuthSessions -->|"Session cache"| Redis
    AnalytEvents -->|"High-throughput ingest"| Kafka
                        

Consistency Boundaries

• Strong consistency: Within each service's schema — all reads after a write within the same service reflect the latest state (PostgreSQL's default READ COMMITTED isolation).
• Eventual consistency: Cross-service data propagation via RabbitMQ — maximum staleness of 5 seconds under normal operating conditions, up to 60 seconds during peak load with message backlog.
• Cache consistency: Redis entries have explicit TTLs (5 minutes for user profiles, 1 minute for stock levels). Write-through invalidation is used: when a service updates data, it publishes a cache invalidation event that all interested services consume.

Deployment Architecture

nullchemy is deployed on Kubernetes (k8s) with a minimum of three worker nodes across two availability zones. Each microservice runs in its own namespace with dedicated service accounts, resource quotas, and network policies. The deployment is managed via Helm charts stored alongside each service's source code.

graph TD
    subgraph K8s["Kubernetes Cluster"]
        subgraph NS1["namespace: nullchemy-system"]
            Ingress["Ingress (nginx)"]
            Kong["Kong API Gateway"]
        end
        subgraph NS2["namespace: nullchemy-services"]
            AuthPod["auth-service (3 replicas)"]
            UserPod["user-service (2 replicas)"]
            NotifPod["notifications-service (2 replicas)"]
            DocPod["documents-service (2 replicas)"]
            InvPod["inventory-service (3 replicas)"]
            AnalytPod["analytics-service (2 replicas)"]
            AuditPod["audit-service (2 replicas)"]
        end
        subgraph NS3["namespace: nullchemy-data"]
            PG["PostgreSQL (StatefulSet)"]
            RedisST["Redis (StatefulSet)"]
            RabbitST["RabbitMQ (StatefulSet)"]
            KafkaST["Kafka (StatefulSet)"]
        end
    end

    Internet["Internet"] --> Ingress
    Ingress --> Kong
    Kong --> AuthPod
    Kong --> UserPod
    Kong --> NotifPod
    Kong --> DocPod
    Kong --> InvPod
    Kong --> AnalytPod
    Kong --> AuditPod
    AuthPod --> PG
    UserPod --> PG
    NotifPod --> PG
    DocPod --> PG
    InvPod --> PG
    AnalytPod --> PG
    AuditPod --> PG
    AuthPod --> RedisST
    UserPod --> RedisST
    NotifPod --> RabbitST
    InvPod --> RabbitST
    AnalytPod --> KafkaST
    AuditPod --> RabbitST
                        

Resource Allocations

Technology Stack

Cross-Cutting Concerns

This section is a stub. Once the following information becomes available, it will cover:

• Distributed tracing strategy: Full OpenTelemetry instrumentation across all 7 services — trace context propagation through Kong, HTTP headers, and RabbitMQ message headers. Jaeger as the trace backend with sampling rate of 10% in production, 100% in staging.
• Centralized configuration management: Kubernetes ConfigMaps for non-sensitive settings, with a migration plan to a dedicated configuration service (or HashiCorp Consul) for runtime reloading without pod restarts.
• Global rate limiting and throttling: Tiered rate limits — per-IP at the Kong gateway (100 req/min), per-user at the service level (1,000 req/min), and per-endpoint for sensitive operations like password reset (5 req/hour).
• Audit trail requirements: All mutating operations (POST, PUT, PATCH, DELETE) across all services must produce an audit event with user ID, timestamp, resource identifier, and old/new values. Retention period: 7 years for compliance, with automated archival to cold storage after 90 days.
• Data retention and archival policies: Per-service data retention rules — audit logs (7 years), notification delivery logs (2 years), analytics raw events (1 year), document versions (all versions retained until parent document deletion + 30 days).

Security Considerations

Failure Modes & Resilience

The following table catalogs the top failure scenarios, their estimated probability, impact severity, and the mitigation strategy in place. Probabilities are based on industry data for similar Kubernetes-deployed microservice platforms operating at comparable scale.

Open Questions

This section is a stub. Once the following information becomes available, it will cover:

• Database instance strategy: Whether to migrate from a shared PostgreSQL cluster (with per-service schemas) to independent RDS instances per service. The trigger for this migration is either (a) exceeding 50K sustained RPS, (b) a service requiring a different database engine (e.g., DynamoDB for analytics), or (c) operational isolation requirements from a specific compliance framework.
• Service mesh adoption: Evaluation of Istio or Linkerd for mTLS, traffic splitting, and fine-grained observability. The current NetworkPolicy-based approach is sufficient for the initial deployment but may not scale to 20+ services.
• Event sourcing for inventory: Whether to adopt a full event-sourcing pattern (Kafka-backed) for the inventory domain, which would enable temporal queries ("what was the stock level at time T?") and simplify the analytics integration. Trade-off: increased operational complexity vs. richer query capabilities.
• Multi-region deployment: Requirements for active-active or active-passive multi-region deployment. This impacts database replication strategy (PostgreSQL logical replication vs. Aurora Global Database), DNS routing (Route 53 latency-based vs. GeoDNS), and data residency compliance.
• API versioning policy: Formalizing the API versioning strategy — currently /api/v1/ is used, but the deprecation window, backward compatibility guarantees, and version sunset process need to be defined with product stakeholders.