Architecture

Provider Pattern

Every major subsystem in SIMPLICITY-ADMIN is defined by a provider interface in the core package. This lets you swap any layer without affecting the rest.

Provider Interfaces

interface DatabaseProvider {
  connect(): Promise<void>;
  introspect(): Promise<SchemaMeta>;
  disconnect(): Promise<void>;
}

interface APIProvider {
  createEndpoints(schema: SchemaMeta): void;
  middleware(): RequestHandler;
}

interface AuthProvider {
  sign(payload: object): string;
  verify(token: string): object;
  refresh(token: string): string;
  hashPassword(plain: string): Promise<string>;
  verifyPassword(plain: string, hash: string): Promise<boolean>;
}

interface UIProvider {
  serve(): RequestHandler;
}

Each built-in package (@mabulu-inc/simplicity-admin-db, @mabulu-inc/simplicity-admin-api, @mabulu-inc/simplicity-admin-auth, @mabulu-inc/simplicity-admin-ui) implements one of these interfaces. To replace a subsystem, implement the interface and register it in your config’s providers object.

Package Dependency Graph

@mabulu-inc/simplicity-admin-core          (zero dependencies on other @simplicity-admin packages)
  |
  +-- @mabulu-inc/simplicity-admin-db      (depends on core + simplicity-schema)
  |     |
  |     +-- @mabulu-inc/simplicity-admin-api   (depends on core + db)
  |     |
  |     +-- @mabulu-inc/simplicity-admin-auth  (depends on core + db)
  |
  +-- @mabulu-inc/simplicity-admin-ui      (depends on core only)
  |
  +-- @mabulu-inc/simplicity-admin-cli     (depends on all other packages)

Key design rule: core has zero dependencies on other @simplicity-admin packages. It defines interfaces, configuration, and the metadata model. Everything else depends on core.

Three Modes, One Engine

All three consumption modes — CLI scaffold, npm install, embeddable middleware — converge on the same core engine:

1. CLI scaffold — The init command generates a project that imports and wires the packages together.
2. npm install — You import the packages directly and use defineConfig() to configure them.
3. Embeddable middleware — createAdmin() wires the packages internally and returns standard HTTP middleware.

Regardless of how you consume SIMPLICITY-ADMIN, the startup sequence is identical:

1. Load and validate configuration (Zod schema)
2. Register providers (built-in or custom)
3. Connect to the database
4. Introspect the schema
5. Initialize API, auth, and UI layers
6. Execute plugin lifecycle hooks
7. Serve

Next Steps

• Schema-as-Truth — How database introspection drives the entire system
• Core Package — Detailed look at the config system, metadata model, and plugin hooks