Build anything. Just describe it.

Building a remote app (Satellite) for the VENI-AI platform is an AI-first experience. You don't need to manually scaffold directories or wire up SSO handshakes—you just describe your business requirements, and the AI handles the implementation.

---

🚀 The AI-Driven Workflow

This guide uses Claude Code or Gemini CLI to do the heavy lifting. The AI understands the entire monorepo architecture, including the Shell integration, Ignis v2 patterns, and security standards.

1. Open your AI Assistant

Open your terminal in the root of the veni-ai monorepo:

Gemini CLI

# Start the interactive engineering agent
gemini

Claude Code

# Start Claude
claude

2. Describe your App

Copy the prompt below, fill in your details, and paste it into the AI assistant.

I want to build a new remote app for the VENI-AI Shell.

App Name: [e.g., Inventory]
Description: [e.g., Track warehouse stock and shipments]
Category: [e.g., Operations]

Features I need:
- [Feature 1: e.g., A searchable table of items with quantity levels]
- [Feature 2: e.g., A button to "Adjust Stock" that opens a modal form]
- [Feature 3: e.g., Automatic color highlighting for low stock items]

Please:
1. Scaffold the app using the 'veni' CLI.
2. Implement the Hono API (Service, Controller, Schema).
3. Implement the React UI (Pages, Hooks, Components).
4. Wire up the SSO handshake and register it with the Shell.
5. Start it locally so I can test it.

3. Review and Refine

The AI will execute the plan, create the files, and run the necessary commands. Once finished, open http://localhost:5173 to see your new app live in the Shell.

You can continue to refine the app with follow-up prompts:

• "Add an 'Export to CSV' button to the inventory table."
• "Only users with the 'Manager' role should see the stock adjustment button."
• "Push these changes to GitHub and deploy to dev."

---

🛠️ Manual Implementation (SCS Reference)

If you prefer to build manually or need to understand the underlying "Integration Contract," follow these patterns.

1. The Shell Integration Contract

Every satellite must expose a ShellEntry component via Module Federation.

// apps/your-app/ui/src/federation/shell-entry.tsx
export default function ShellEntry() {
  const basename = window.location.pathname.startsWith('/your-app') ? '/your-app' : '/';
  return (
    <BrowserRouter basename={basename}>
      <App />
    </BrowserRouter>
  );
}

2. The Identity Handshake

The Shell broadcasts its JWT via BroadcastChannel. Your app must listen and exchange it for a local service-scoped token.

Component	Responsibility
token-broadcast.ts	Listens for Shell JWTs and decodes user info.
token-exchange.ts	Calls POST /api/auth/exchange to get a satellite-scoped JWT.
api-client.ts	Axios instance that automatically attaches the scoped token to all requests.

3. Backend Verification (RS256)

Your satellite API must verify the Shell's JWT using the public JWKS endpoint: http://shell-api:3000/api/.well-known/jwks.json

---

📦 Reference Implementations

The monorepo includes production-ready apps you can use as blueprints:

App	Highlights
Drive	Hierarchical folders, S3/MinIO integration, and full-text search.
HRM	Complex CRUD, role-based UI visibility, and org-chart rendering.
Documents	Rich-text editing, version history, and approval workflows.

---

Pro Tip

The AI is most effective when you describe Intent ("I want to track stock") rather than Implementation ("Create a file named ItemController.ts"). Trust the AI to follow the platform standards.