# Benuspace Agentic Platform — AGENTS.md

> Guide for AI agents and developers working in this repository.  
> Domain: **benuspace.com** | Primary market: **West Africa (XOF)** | Currencies: **XOF, EUR, USD**

## Platform purpose

Benuspace is a **dual-consumption** platform:

- **Humans** use the **PWA** (`apps/web-bff`) with role-based navigation.
- **AI agents** use the **MCP gateway** (`apps/mcp-gateway`) for catalogue discovery and wallet-backed purchases.

Business model: **marketplace-first**, native FinTech/MarTech agents, B2A directory, outcome-based pricing (future).

## Repository layout

```
apps/
  web-bff/              Next.js 15 PWA (GraphQL BFF to PWA)
  identity-service/     Auth, RBAC, API keys, MCP tokens, tenancy
  catalogue-service/    Global catalogue, vendor listings, MCP manifests
  commerce-service/     Wallets, invoicing, AML, commissions
  notification-service/ Web Push via Kafka events
  agent-runtime/        Native agents (Node workers + rules engine)
  mcp-gateway/          MCP HTTP/SSE + stdio entrypoint
packages/
  types/                Shared TypeScript types
  config/               Environment loading (Zod)
  logger/               Pino logger + correlation IDs
  kafka/                Kafka producers/consumers
  storage/              MinIO client + bucket helpers
  server/               Fastify + Apollo bootstrap
deploy/
  helm/                 Kubernetes Helm charts
  docker/               Shared Docker build
tests/
  bdd/                  Cucumber BDD (cross-service MVP gate)
docs/
  JIRA_BACKLOG.md       Epic/Feature/Story backlog (Jira substitute; E11 Benumail Admin)
  BENUMAIL_ADMIN.md     Platform Mail API contract for web-bff /admin/mail
```

## Services & ports (local dev)

| Service              | Port | Database              |
|----------------------|------|-----------------------|
| web-bff              | 3000 | —                     |
| identity-service     | 3001 | bs_agentic_identity   |
| catalogue-service    | 3002 | bs_agentic_catalogue  |
| commerce-service     | 3003 | bs_agentic_commerce   |
| notification-service | 3004 | bs_agentic_notification |
| agent-runtime        | 3005 | bs_agentic_agent      |
| mcp-gateway          | 3006 | —                     |

## MCP tools (v1)

| Tool                  | Description                                      |
|-----------------------|--------------------------------------------------|
| `search_catalogue`    | Query global catalogue (100 req/min per API key) |
| `get_product_manifest`| Product MCP manifest (auto-generated on publish) |
| `execute_purchase`    | Debit client wallet (requires `client_id` context) |
| `get_wallet_balance`  | Read wallet for target client                    |
| `register_agent_run`  | AI Act audit trail entry                         |

**Transport:** HTTP/SSE (remote) and stdio (embedded).  
**Auth:** MCP tokens; enterprise tokens may act across multiple clients — always pass `client_id`.

## Kafka topics

Prefix: `bs.agentic.*` — see `@benuspace/types` (`KAFKA_TOPICS`) and [docs/KAFKA_TOPICS.md](./docs/KAFKA_TOPICS.md).

## MinIO buckets

`manifests`, `invoices`, `uploads`, `reconciliation` — see `@benuspace/types` (`MINIO_BUCKETS`).

## MVP release gate (Cucumber)

1. Agency manager onboards FinTech reconciliation agent for SME client (PWA).
2. Enterprise agent purchases MarTech tool via MCP with wallet debit (staging).

## Conventions

- **Node.js 22**, **pnpm workspaces**, **TypeScript strict**, **Vitest**, **Cucumber**.
- **Correlation ID:** `X-Correlation-Id` header on all HTTP calls.
- **Tenancy:** SME = row-level `tenant_id`; Enterprise = DB-per-tenant.
- **No PII in Qdrant** — redacted embeddings only; sensitive data in PostgreSQL.
- **Audit events** to Kafka (`bs.agentic.audit.event`); 7-year retention target.

## CI/CD branches

| Branch    | Environment | Deploy      |
|-----------|-------------|-------------|
| `develop` | dev         | automatic   |
| `staging` | staging     | automatic   |
| `main`    | production  | manual gate |

Registry: GitLab `CI_REGISTRY` (Nexus).

## Local development

```bash
corepack enable
pnpm install
pnpm dev:infra          # PostgreSQL, Kafka, Qdrant, MinIO
pnpm --filter @benuspace/identity-service dev
pnpm --filter @benuspace/web-bff dev
```

## Do not

- Store raw card data (PCI deferred).
- Put financial PII in vector memory.
- Skip `client_id` on cross-tenant MCP calls.