System Overview

Component diagram

Request flow — OAuth login

1. Browser  → GET /api/auth/login
2. Shell API → Redis: store { codeVerifier, providerId } with state key (TTL 600s)
3. Shell API → 302 → Keycloak public URL (/authorize?code_challenge=...&state=...)
4. Keycloak  → 302 → /api/auth/callback?code=...&state=...
5. Shell API → Redis: retrieve codeVerifier by state
6. Shell API → Keycloak internal URL (/token, code_verifier=...)
7. Keycloak  → Shell API: Keycloak tokens
8. Shell API → create/update user in PostgreSQL → issue Shell JWT
9. Shell API → 302 → Shell UI with Shell JWT
10. Shell UI → BroadcastChannel: broadcast Keycloak token to remote micro-frontends

Directory structure

veni-ai/
├── shell/
│   ├── api/                  Shell API (Bun + Hono + Ignis)
│   │   ├── src/
│   │   │   ├── controllers/  HTTP handlers
│   │   │   ├── services/     Business logic
│   │   │   ├── repositories/ Drizzle DB access
│   │   │   ├── schemas/      Drizzle table + Zod validation schemas
│   │   │   ├── models/       TypeScript interfaces
│   │   │   ├── middleware/   RBAC, rate limit, CORS
│   │   │   ├── strategies/   JWT auth strategy
│   │   │   └── config/       env.config.ts (Zod validation)
│   │   ├── config/           rbac_model.conf (Casbin)
│   │   └── database/
│   │       └── migrations/   Drizzle migration files
│   └── ui/                   Shell UI (React 18 + Vite + MF)
│       └── src/
│           ├── app/          Admin.tsx root, AppProviders
│           ├── pages/        Route components
│           ├── components/   Shared UI components
│           ├── context/      AuthProvider, DataProvider
│           ├── hooks/        Data + auth hooks
│           ├── api/          ApiClient (axios wrapper)
│           └── federation/   Module Federation config + loader
├── infrastructure/
│   └── k8s/
│       ├── base/             Base K8s manifests
│       └── overlays/
│           ├── dev/          Dev-specific patches + secrets.env
│           ├── uat/
│           └── prod/
├── protos/                   .proto definitions for gRPC
├── cli/                      veni CLI source
└── scripts/
    └── deploy.sh             kustomize + kubectl deploy