What is the Fleapo Marketplace

The Fleapo AI Marketplace is a catalog, an identity provider, and a billing layer for independent AI agents. It is not an agent runtime.

That distinction is the single most important thing to understand before reading the rest of these docs. Everything below follows from it.

The three roles the marketplace plays

Role	What it means	Where it lives
Catalog	The public face of every agent — name, tagline, capabilities, steps, screenshots, reviews, pricing tiers, install counts	marketplace-fleapoai-service (NestJS) + fleapo-marketplace (React)
Identity Provider	OIDC server that issues access/ID/refresh tokens. Each agent is a registered OAuth client	better-auth inside marketplace-fleapoai-service, exposed at /api/auth/* and /api/auth/oauth2/*
Billing layer	Stripe Products + Prices per pricing tier, subscription lifecycle, metered quotas, usage ledger	src/pricing/, src/subscriptions/, src/stripe/, src/webhooks/, src/usage/

What the marketplace is NOT

It does not execute agent logic. There is no endpoint anywhere that runs an agent. The backend has no proxy, no message queue, no inference orchestration, no webhook callbacks to agent services.

If you look in src/interactions/, you'll find what sounds like a runtime ("interactions"). It is not — it is a marketing event log (signups, demo requests, waitlist hits, subscription created), used to fan out emails to admin recipients. It has no relationship to user-facing agent execution.

The marketplace's only runtime concern is billing and quota arithmetic: an agent service tells the marketplace "I'm about to consume one of X units", and the marketplace says yes (and increments) or no (429).

What "an agent" actually is

An agent in this system is two things stitched together:

1. A catalog listing in the marketplace database (agents table) — metadata, OAuth client credentials, pricing tiers, capabilities, steps, screenshots, reviews.
2. A separate hosted service — built and operated independently, anywhere. The canonical reference implementation is agent-poc / VoxaAI, a Node + Express + MongoDB stack that:
   • acts as an OAuth Relying Party against the marketplace,
   • reads the user's active subscription and per-metric quotas from /me/subscriptions/:agentId and /me/agents/:agentId/usage,
   • calls POST /me/agents/:agentId/usage/:metricSlug/consume before chargeable actions,
   • implements its own UI, data layer, and domain logic.

The two are linked by the agent's id / slug and its OAuth clientId — both issued by the marketplace at registration time.

Why this split exists

It buys three properties that matter:

• Agents can be built in any stack. VoxaAI uses Node + MongoDB. The next agent could be Python + Postgres, or Go + Redis. The marketplace doesn't care.
• Agents own their own infrastructure cost. Heavy stuff (Puppeteer, LiveKit avatars, vector DBs) lives in the agent's own AWS/GCP/Railway/Vercel — never the marketplace's.
• The marketplace stays small. It's a catalog + IdP + billing service. It can scale horizontally without dragging agent runtime concerns along.

The shape of the rest of these docs

• Add a New Agent is the headline journey. It splits into three independent tracks (build the service, register the listing, wire the UI) that you'll work through in parallel.
• Concepts gives one page per domain object (Agent, Capability, Step, Pricing Tier, Metric, Quota, Install, Subscription, Interaction, Review, OAuth, Stripe).
• Flows is the same material from the other angle — sequence diagrams of who calls whom in each user-visible flow.
• API Reference is auto-generated from openapi.json. Every endpoint, every schema, with a try-it-out console.
• Frontend and Backend references catalog everything inside each repo.
• Operations, Security, Troubleshooting, Contribution cover the rest.

Read the architecture page next.