Module map

marketplace-fleapoai-service/src/ directory listing, annotated.

Top-level files

File	Role
app.module.ts	Root module; wires middleware, global pipes, all feature modules
main.ts	Bootstrap, global pipes/interceptors/CORS, listens on PORT
seed.ts	Standalone — creates initial platform admin via better-auth

Cross-cutting modules

Path	Role	Public surface
config/	AppConfigService — typed env vars, @Global() module	injected token AppConfigService
common/	Shared types, interceptors, error mapping	ApiResponse<T>, error codes
db/	Drizzle module providing DRIZZLE + PG_POOL tokens	@Inject(DRIZZLE)
auth/	better-auth wrapper, controllers, guards, permissions	/api/auth/*, PlatformAdminGuard, etc.
logging/	Audit log middleware + service + PostHog batcher	(middleware)
stripe/	Stripe SDK module — DI-provided Stripe client	injected STRIPE
health/	/health controller	GET /health

Feature modules

agents

File	Role
agents.controller.ts	CRUD endpoints
agents.service.ts	Business logic; creates OAuth client at create time
dto/	CreateAgentDto, UpdateAgentDto, QueryAgentDto, AgentDto

Endpoints (all under /agents): list, by-slug, by-id, create, update, delete, demo-request. See Concept: Agent.

capabilities

CRUD on agent_capabilities under /agents/:agentId/capabilities.

steps

CRUD on agent_steps under /agents/:agentId/steps.

changelog

CRUD on agent_changelog under /agents/:agentId/changelog.

pricing

File	Role
pricing.controller.ts	Tier CRUD + checkout
pricing.service.ts	Creates Stripe Product+Price for paid tiers; archives on delete
tier-quotas.controller.ts	Per-tier quota matrix endpoints
tier-quotas.service.ts	Reads/writes tier_metric_quotas
dto/	CreateTierDto, etc.

Endpoints: /agents/:agentId/pricing/*, /agents/:agentId/pricing/:tierId/checkout, /agents/:agentId/pricing/:tierId/quotas/*.

metric-definitions

CRUD on agent_metric_definitions under /agents/:agentId/metric-definitions. slug and kind immutable.

subscriptions

File	Role
subscriptions.controller.ts	/me/subscriptions/*, /agents/.../checkout
subscriptions.service.ts	Checkout, list, get, cancel, webhook handlers helpers, returnUrl validation, interaction recording

usage

/me/agents/:agentId/usage[*]/consume/release + admin addon endpoints. Atomic transactional logic for quota arithmetic. See Concept: Metric & Quota.

webhooks

File	Role
stripe-webhook.controller.ts	POST /webhooks/stripe (raw body, signature header)
stripe-webhook.service.ts	Signature verify, idempotent dispatch via stripe_events, per-event handlers

installs

POST /agents/:agentId/install. Idempotent UPSERT.

interactions

File	Role
interactions.controller.ts	/admin/interactions/*
interactions.service.ts	record() + recipient mgmt
interactions.singleton.ts	App-wide service singleton for fan-out emails

Despite the name, NOT runtime — see Concept: Interaction.

reviews

/agents/:agentId/reviews (list, upsert) + /reviews/:id (delete). Upsert via unique (agentId, userId).

tags

/tags list/create/delete. M:N via agent_tags.

waitlist

/agents/:agentId/waitlist + /agents/:agentId/waitlist/me. Idempotent email capture + auto-fans into interactions.

upload

File upload endpoint. Storage provider configured via env.

metrics

Public agent metrics aggregations (agent_metrics_daily). Read-only.

Module registration order

AppModule imports in this order:

1. ConfigModule (global)
2. DrizzleModule (global)
3. AuthModule (provides AUTH token, requires DRIZZLE + AppConfigService)
4. LoggingModule (audit batching)
5. All feature modules
6. WebhooksModule (depends on SubscriptionsModule)

Adding a new module

See Contribution → Adding a backend module.