SnapNGo Architecture

What the SnapNGo CLI builds: host shell + domain MFEs over a single API gateway to ownership-clear microservices. Shared packages carry contracts and telemetry. Modules attach without rewriting the spine.

Project

SnapNGo

Audience

Lead eng · architects

Stack

CLI · MFEs · Gateway · Microservices

System map

┌──────────────────────────────────────────────────┐
│                    Host Shell                    │
│              (auth context · MF load)            │
│  ┌──────────┐ ┌───────────┐ ┌────────────┐       │
│  │ Auth MFE │ │ Domain    │ │ Domain     │  …    │
│  │          │ │ MFE …     │ │ MFE …      │       │
│  └────┬─────┘ └─────┬─────┘ └─────┬──────┘       │
└───────┼─────────────┼─────────────┼──────────────┘
        │             │             │
        └─────────┐   │   ┌─────────┘
                  ▼   ▼   ▼
┌──────────────────────────────────────────────────┐
│                   API Gateway                    │
│         JWT · rate-limit · x-user-* inject       │
└───┬─────────┬──────────┬──────────┬──────────────┘
    ▼         ▼          ▼          ▼
  auth     billing    domain MS   domain MS …
    │         │          │          │
    └─────────┴──────────┴──────────┘
              Postgres · Redis · object storage

packages (import, not deploy):
  @snapngo/shared · @snapngo/observability
  product UI packages per vertical (@taxbox/ui, @listia/ui, …)

CLI:
  snapngo init | add | up  →  spine + module compose / env / CI stubs

Spine vs modules

The spine holds identity defaults, networking, gateway, observability hooks, and org tenancy. Modules declare ports, env keys, lifecycle scripts, and optional UI remotes. Add or remove a module without rewriting auth or the host shell.

Gateway as trust boundary

• Single public HTTP door for browsers and remotes
• Verify JWT (or device token where used); inject x-user-* / active org
• Strip bearer after verify; proxy by path prefix
• Block service-internal routes from the public edge

Service ownership

• auth — users, sessions, orgs, members, roles
• billing — SaaS subscription entitlement (merchant pays platform)
• domain MS — vault, catalog, inventory, … one write model each
• gateway — no business source of truth

Shared packages

• @snapngo/shared — errors, OpenAPI helpers, header names, ports
• @snapngo/observability — Pino / OTEL middleware
• Product UI packages — tokens and components for host + remotes

CLI / generators

Module registry, compose/env generators, idempotent apply. Engineers run init / add / up; the topology above is what gets emitted and run. Re-run configure to converge, not duplicate. Generated files stay owned by the tool until marked customized.