System overview
Agentful is a Node 24 monorepo built around one source of truth: the database schema and shared TypeScript/Zod contracts.
Workspace Layout
Section titled “Workspace Layout”| Path | Purpose |
|---|---|
apps/api |
NestJS API, MCP server, payments, plugins, events, repositories |
apps/web |
React storefront and account UI built with Vite+ |
apps/docs |
Astro Starlight documentation site |
packages/shared-types |
Zod schemas and shared inferred types |
packages/plugin-sdk |
Plugin authoring helpers |
packages/test-report |
Holistic testing report renderer |
db |
SQL migrations and seed data |
tools/release |
Safe update and migration helpers |
tools/scripts |
Mutation registry, reporting, and bootstrap utilities |
Data Flow
Section titled “Data Flow”- Storefront and admin clients call the API.
- The API validates boundaries with shared schemas.
- Repositories write to Postgres.
- Domain state changes publish commerce events in the same transaction.
- MCP tools expose typed operations over the same services.
- Plugins can subscribe to events or extend declared surfaces.
Why Runtime Settings Matter
Section titled “Why Runtime Settings Matter”Settings are database records, not source patches. The storefront reads them
through GET /storefront/config and resolves bundled theme/content behavior at
runtime. This is the mechanism that lets agents make safe changes without
fighting future updates.
Internal Package Scope
Section titled “Internal Package Scope”The public app is Agentful. The current internal package scope is still
@shop/*; docs call this out where it matters so plugin authors and
contributors can use the correct imports today.