444516e900
The browser RAG (@crema/lexical-rag-ui) and the server RAG (arcadia-search) coexist in this app, and the agent picks between them via tool descriptions. The two libs each have their own README, but neither covers the picking decision or how they relate. This doc fills that gap. - At-a-glance table: lib, engine, runtime location, corpus size, update cadence, auth, agent tool, what it's best for. - The system-prompt snippet that drives tool picking, with notes on observed DeepSeek V3 behavior. - Per-surface deep dive (build path, tools, storage, limits, why it exists). - Why both run by default (always-on fallback, A/B regression). - Decision checklist for adding new corpora. - "What lives where" cheat sheet pointing at the right file in the right repo for common tasks. Cross-references arcadia-search's README.md, MULTI_TENANT.md, and ARCADIA_INTEGRATION.md so a reader landing here can navigate to the right rabbit hole. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Arcadia Admin
Admin webapp for arcadia-core — the multi-tenant Phoenix backend. Built on the Crema design system with the Skyrise theme and started from the Vibespace starter.
Surfaces tenant management, user/role administration, billing, audit logs, storage configs, scheduled tasks, feature flags, and platform monitoring on top of arcadia's /api/v1 and /admin/* endpoints.
Quick start
npm install
npm run dev
Open http://localhost:5173. The app talks to arcadia at http://localhost:4000 by default; override with VITE_ARCADIA_URL in .env.local.
To use it for real:
- Have arcadia running locally (see
../reference/arcadia-app/DEV_SETUP.md). - Visit
/loginand sign in with admin credentials. In dev seeds:admin@example.com/AdminP@ssw0rd(tenantdefault).
Configuration
| Env var | Default | Purpose |
|---|---|---|
VITE_ARCADIA_URL |
http://localhost:4000 |
Base URL of arcadia-core. |
VITE_ARCADIA_TENANT |
default |
Tenant id sent as X-Tenant-ID. Override per-deployment. |
What's in here
App shell
app/components/layout/app-shell.tsx — left rail + appbar + avatar dropdown. Brand identity in app/lib/identity.ts (name: "Arcadia Admin", icon: Shield). The shell is template code, not a lib — fork it freely as admin features are added.
Arcadia client + auth UI
@crema/arcadia-client— typed HTTP client (generic + openapi-fetch-backedclient.typed), Phoenix Channels realtime, error normalization. Mounted at the root via<ArcadiaProvider>.@crema/arcadia-auth-ui— login / signup / password reset / 2FA forms, themed via Skyrise tokens. The/loginroute renders<LoginForm>.
Skyrise theme
lib-theme-skyrise — premium AI-first glass: iridescent body, frosted-glass surfaces, vivid text, Apple-spring motion. Default 18px root.
Surface tints (body[data-surface="snow|stone|sage|slate"]) and dark mode (html.dark) work out of the box via the existing pickers in the appbar.
Command bus
@crema/action-bus — every interactive element has data-action="<id>" so admin flows can be scripted, e2e-tested, or driven by an LLM through a single bus. See docs/AI_FIRST.md.
Sibling repos
your-workspace/
arcadia-admin/ ← this repo
vibespace/ ← starter that this was cloned from
reference/arcadia-app/ ← Phoenix backend (read-only reference)
lib-arcadia-client/
lib-arcadia-auth-ui/
lib-action-bus/
lib-aifirst-ui/
lib-chat-ui/
lib-llm-ui/
lib-notification-ui/
lib-theme-skyrise/
Dev scripts
| Command | What it does |
|---|---|
npm run dev |
Vite dev server |
npm run build |
Production build |
npm run start |
Serve the built app |
npm run typecheck |
react-router typegen && tsc |
npm run test |
Vitest run |
bash start.sh / bash stop.sh |
Run dev server in the background |
Conventions
- Brand strings, not literals. Use
useBrand().name— never hardcode "Arcadia Admin". [data-action="<id>"]on every interactive element. Naming:nav-*,appbar-*,tenants-*,users-*,audit-*, etc.- Tokens, not values.
bg-card,text-foreground,var(--primary)— never hex. - Lib edits commit to each lib's own repo.
git statushere only shows app-level changes.
Further reading
docs/AI_FIRST.md— command-bus / DSL system tourapp/components/layout/THEME_CONTRACT.md— token contract every theme must satisfyCLAUDE.md— orientation for an LLM working in this repo../reference/arcadia-app/— backend (DEV_SETUP, controllers, OpenAPI source-of-truth)