Architecture Overview

FluxKit is built around a modular architecture where each wire operates independently while sharing a common foundation.

Design Principles

1. Modular -- Install only the wires you need. No bloat.
2. Convention over Configuration -- Sensible defaults; override when necessary.
3. Dual Interface -- Every wire (except UI) exposes both a programmatic API and a REST API.
4. Database-First -- MongoDB is the single database layer, shared across all wires.
5. AI-Friendly -- APIs are designed to be easily consumed by AI agents and LLMs.

System Diagram

┌─────────────────────────────────────────────────────────┐
│                      Your Application                    │
├─────────────────────────────────────────────────────────┤
│                        FluxKit Core                      │
│  ┌─────────┐ ┌──────┐ ┌──────────┐ ┌────────┐ ┌─────┐ │
│  │  Config  │ │Logger│ │Validation│ │ Crypto │ │ HTTP │ │
│  └─────────┘ └──────┘ └──────────┘ └────────┘ └─────┘ │
│  ┌──────────────────────────────────────────────────┐   │
│  │                   MongoDB Driver                  │   │
│  └──────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────┤
│                         Wires                            │
│  ┌──────┐ ┌─────────┐ ┌─────┐ ┌─────┐ ┌───────┐       │
│  │ Auth │ │Messaging│ │Store│ │ Pay │ │Onchain│       │
│  └──┬───┘ └────┬────┘ └──┬──┘ └──┬──┘ └───┬───┘       │
│     │          │         │       │         │            │
│  ┌──┴──────────┴─────────┴───────┴─────────┴──┐        │
│  │              REST API Router                │        │
│  └────────────────────────────────────────────┘        │
├─────────────────────────────────────────────────────────┤
│                     UI Wire (React)                      │
│  ┌────────────┐ ┌────────┐ ┌───────┐                    │
│  │ Components │ │Theming │ │ Hooks │                    │
│  └────────────┘ └────────┘ └───────┘                    │
└─────────────────────────────────────────────────────────┘

How Wires Connect

When you instantiate FluxKit, you pass in the wires you want:

import { FluxKit } from "@fluxkitdev/core";
import { auth } from "@fluxkitdev/auth";
import { messaging } from "@fluxkitdev/messaging";

const app = new FluxKit({
  wires: [auth(), messaging()],
  database: { uri: process.env.MONGODB_URI },
});

During startup, FluxKit:

1. Loads configuration from environment variables and any config files.
2. Connects to MongoDB using the provided URI.
3. Initializes each wire in order, injecting shared dependencies (database, config, logger).
4. Mounts REST routes for each wire under its namespace (e.g., /auth/*, /messaging/*).
5. Starts the HTTP server on the specified port.

Wire Lifecycle

Each wire follows a consistent lifecycle:

initialize() → configure() → registerRoutes() → ready()

• initialize -- Wire receives the shared context (db, config, logger).
• configure -- Wire reads its specific configuration and sets up providers.
• registerRoutes -- Wire mounts its REST API endpoints on the shared router.
• ready -- Wire signals it is ready to handle requests.

Shared Context

All wires share a context object that includes:

Property	Type	Description
db	Db	MongoDB database instance
config	Config	Merged configuration object
logger	Logger	Structured logger instance
crypto	Crypto	Cryptographic utilities
validator	Validator	Schema validation utilities

REST API Conventions

Every wire's REST API follows consistent conventions:

• Routes are namespaced: /auth/*, /messaging/*, /store/*, etc.
• Standard HTTP methods: GET, POST, PUT, DELETE
• JSON request and response bodies
• Error responses follow a standard format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {}
  }
}

Database

FluxKit uses MongoDB as its database. Each wire manages its own collections, prefixed by the wire name:

• auth_users, auth_sessions
• messaging_logs, messaging_templates
• store_files, store_backups
• pay_transactions, pay_subscriptions
• onchain_wallets, onchain_transactions

This avoids collisions and makes it easy to reason about data ownership.

Next Steps

• Core Wire -- Deep dive into the foundational wire
• Installation -- Set up your first FluxKit project