Bu Challenge – Pluggy + Next.js + Supabase + Hono

This repository is a monorepo prepared for a coding task that evaluates:

• Next.js App Router APIs
• API service integrations via Hono (Cloudflare Workers)
• shadcn/ui + Tailwind UI usage (shared @bu-challenge/ui package)
• Supabase authentication and storage
• Swagger/OpenAPI documentation
• AI-driven enrichment using ai SDK and Cloudflare Workers AI
• Most importantly: Pluggy integration (transactions, enrichment, and PIX transfers)

Monorepo Structure

• apps/app: Next.js 15 App Router. Provides UI and API routes that call the Hono engine.

  • src/app/page.tsx: Landing page.
  • src/app/dashboard/page.tsx: PIX transfer form + enriched transactions table.
  • src/app/api/pluggy/transactions/route.ts: Proxies to engine /transactions and returns enriched transactions.
  • src/app/api/pluggy/pix-transfer/route.ts: Proxies to engine /pix/transfer.
  • src/app/api/enrich/route.ts: Supabase example endpoint saving enrichment payloads.
  • src/app/api/auth/bu/callback/route.ts: Example auth callback for Supabase.

• apps/mini-motora: Cloudflare Workers API using Hono with OpenAPI. Exposes typed client via @bu-challenge/mini-motora/client.

  • src/index.ts: App setup, middleware, Swagger, and routes.
  • src/routes/transactions: Fetches transactions from Pluggy.
  • src/routes/enrich: Enrich transactions using Workers AI.
  • src/routes/pix: NEW. Template for PIX transfer endpoint to finish.
  • src/providers/pluggy: Pluggy provider + API wrapper. Add/fix methods here.
  • src/client/index.ts: Typed client used by the Next.js app.

• packages/ui: Shared Tailwind + shadcn component library.

• packages/supabase: Shared Supabase helpers for client/server in Next.js.

Task

Finish Pluggy integration in mini-motora (PIX transfers + transaction enrichment):

1. Build a sharable baseline package @bu-challenge/mini-motora for Pluggy.
2. Enrich Pluggy transactions (Give each transaction recored in a bank account connected via Pluggy widget a category).
3. Implement PIX transfers using Pluggy docs.
4. Add a super simple UI in the Next.js app to trigger PIX transfers and to connect bank accounts for enrichment to commence.

What’s Missing (Your Task)

• Pluggy Integration

  • The Pluggy client is in apps/mini-motora/src/providers/pluggy/pluggy-api.ts but PIX is a template only.
  • Implement:
    • getTransactions(accountId) (validate/adjust; it works for item-based accountId format itemId_accountId).
    • enrichTransactions(transactions) (route exists in /enrich, ensure it is used via the app or create a direct helper).
    • createPixTransfer(fromAccountId, toAccountId, amount) in Hono endpoint POST /pix/transfer using Pluggy docs.

• API Endpoints to be used via Next.js App Router API

  • In apps/app/src/app/api/pluggy/transactions/route.ts:
    • Finish /transactions (fetch + enrich if desired; currently fetches transactions from the engine).
  • In apps/app/src/app/api/pluggy/pix-transfer/route.ts:
    • Finish /pix-transfer (initiate transfer by calling engine /pix/transfer).

• UI

  • In apps/app/src/app/dashboard/page.tsx:
    • There is a form to trigger a PIX transfer and a table to display enriched transactions.
    • You must also add a Pluggy Connect flow (frontend) to link bank accounts. A starter API route exists at apps/app/src/app/api/pluggy/link-token/route.ts which gets a Pluggy connect token from the engine. Mount Pluggy’s Connect widget with that token and complete a sandbox connection so enrichment can commence.
  • There is a packages/ui folder ready to use (shadcn components & Tailwind styles).

Notes:

• The Pluggy integration is not finished. The createPixTransfer method in pluggy-api.ts returns a placeholder. Replace it with a real implementation using Pluggy PIX/Payments documentation.
• A new PIX transfer endpoint is wired at apps/mini-motora/src/routes/pix/index.ts → POST /pix/transfer. Complete the implementation.
• Sandbox requirement: enable PIX between two sandbox users (transfer from one account to a separate user). Add any needed connector setup.
• Bank account connection is part of the frontend task. Implement Pluggy Connect in the Dashboard so users can connect at least one sandbox bank account.

How to Run

Prerequisites:

• Bun (bun -v), Node 20+, and Wrangler (npm i -g wrangler).

1. Install dependencies

bun install

2. Environment variables

• Copy apps/mini-motora/.dev.vars.example → .dev.vars and fill:

  • PLUGGY_CLIENT_ID
  • PLUGGY_SECRET
  • API_SECRET_KEY
  • BACKEND_URL=http://localhost:3002

• For Next.js (apps/app), create .env.local with:

NEXT_PUBLIC_ENGINE_API_URL=http://localhost:3002
API_SECRET_KEY=secret
NEXT_PUBLIC_SUPABASE_URL=...your supabase url...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...your supabase anon key...

3. Start services

# Terminal A (root)
bun run dev

# This runs both app and engine via turbo scripts:
# - apps/app (Next.js at http://localhost:3000)
# - apps/mini-motora (Hono at http://localhost:3002)

4. Open docs

• Hono Swagger: http://localhost:3002/swagger (or /)
• App: http://localhost:3000

Supabase Auth Setup

Use the provided callback route apps/app/src/app/api/auth/bu/callback/route.ts.

Steps:

• In Supabase, configure OAuth provider(s) as desired. Set the redirect URL to:
  • http://localhost:3000/api/auth/bu/callback
• Ensure environment variables are set in Next.js .env.local.
• On successful auth, the callback stores cookies and redirects.

Where to Implement Things

• Pluggy client and API calls

  • apps/mini-motora/src/providers/pluggy/pluggy-api.ts
  • Add real createPixTransfer calling Pluggy endpoints (auth via POST /auth with clientId/clientSecret, then PIX transfer endpoints per Pluggy docs).

• Hono endpoints

  • apps/mini-motora/src/routes/pix/index.ts → POST /pix/transfer
  • apps/mini-motora/src/routes/transactions/index.ts → GET /transactions
  • apps/mini-motora/src/routes/enrich/index.ts → POST /enrich

• Next.js App Router APIs (proxies to Hono)

  • apps/app/src/app/api/pluggy/transactions/route.ts
  • apps/app/src/app/api/pluggy/pix-transfer/route.ts
  • apps/app/src/app/api/pluggy/link-token/route.ts

• UI with shadcn/tailwind

  • apps/app/src/app/dashboard/page.tsx (uses @bu-challenge/ui components)
  • Tailwind CSS is imported in apps/app/src/app/layout.tsx from the shared UI package.

References

• Supabase: https://supabase.com/docs
• shadcn/ui: https://ui.shadcn.com/
• Tailwind CSS: https://tailwindcss.com/docs/installation
• Hono: https://hono.dev/
• Swagger/OpenAPI with Hono: https://github.com/honojs/middleware/tree/main/packages/zod-openapi
• Vercel AI SDK (ai): https://sdk.vercel.ai/
• Pluggy Docs: https://docs.pluggy.ai/

Acceptance Criteria

• Engine exposes working endpoints:

  • GET /transactions?provider=pluggy&accountId=...&accountType=depository&latest=true
  • POST /enrich accepts transactions and returns enrichment payload
  • POST /pix/transfer initiates PIX transfer in sandbox
  • POST /auth/pluggy/link returns a connect token for the widget

• Next.js app:

  • Dashboard allows initiating PIX transfers
  • Shows enriched transactions in a table
  • Implements Pluggy Connect to link a bank and produce an accountId usable for transactions/enrichment

• Code quality:

  • Typed, minimal console noise
  • Readable, small modules

Good luck!