Reef UI Frontend (Remix)
Relevant source files
The following files were used as context for generating this wiki page:
Reef is the shared human interface for the Coral project. It operates as a web application built using React Router (formerly Remix) and also functions as the UI layer within the Coral Desktop application. Reef handles user interactions, provider configurations, and activity visualization while communicating with the Coral runtime via gRPC over HTTP/2.
Sources: apps/reef/README.md:1-5, apps/desktop/README.md:3-7
Architecture and Durable Boundaries
Reef follows a strict architectural separation between data fetching and presentation. Presentation modules (components and views) render data provided by loaders and submit changes through fetchers. They do not initiate direct data fetching or import server-only modules.
Component Structure
The UI is organized into three primary directories:
- Wax (
apps/reef/app/wax): Owns reusable visual behavior, styling, and UI primitives (Typography, Buttons, Tables). - Views (
apps/reef/app/views): Composes Wax primitives to build specific application screens and layouts. - Components (
apps/reef/app/components): Contains app-specific shared components that are not generic primitives.
Sources: apps/reef/app/tests/architecture.test.ts:16-20, AGENTS.md:143-147
Data Flow Logic
Reef uses React Router loaders for initial data and actions for mutations. Live updates are handled exclusively via a single streaming connection in apps/reef/app/lib/activity-stream.ts.
The diagram above illustrates the request-response cycle and live update flow within the Reef architecture.
Sources: apps/reef/app/tests/architecture.test.ts:225-245, AGENTS.md:155-159
Authentication and Session Management
Reef supports multiple authentication modes, primarily managed through environment variables. It utilizes secure, host-prefixed cookies for session and CSRF protection.
Configuration Options
| Variable | Description | Default |
|---|---|---|
CORAL_WEB_AUTH_MODE | Sets auth behavior (e.g., required). | disabled (dev) |
CORAL_WEB_PUBLIC_URL | The single public identity/origin of the Reef instance. | Required in prod |
CORAL_WEB_SESSION_SECRET | Secret for encrypting session cookies. | Required in prod |
CORAL_ENDPOINT | The Reef-to-Coral data-plane gRPC address. | Required for auth |
CORAL_WEB_SESSION_MAX_AGE_SECONDS | Maximum duration of a Reef session. | 3600 |
Sources: apps/reef/README.md:24-60
Security Constraints
- Cookies: Uses
__Host-coral_web_sessionand__Host-coral_web_session_csrfprefixes over HTTPS to prevent domain-scoped session injection. - CSRF: Every route action must start with
mutationForm(request, context)to validate methods, origins, and CSRF tokens. - Origin Checks: Reef allows the host defined in
CORAL_WEB_PUBLIC_URLthrough React Router's origin check, supporting TLS-terminating proxies.
Sources: apps/reef/README.md:85-95, apps/reef/app/tests/architecture.test.ts:365-375
The Wax Component Library
Wax is the foundation for all visual elements in Reef. It uses vanilla-extract for type-safe CSS-in-JS styling instead of Tailwind.
Design Principles
- Simplified Technical English: Instructions use the active voice, present tense, and address the reader as "you".
- Accessibility: Status and meaning must not be conveyed by color alone (WCAG 1.4.1); icons or text must accompany color changes.
- Layered Styles: Third-party stylesheets must arrive through an
@importthat names a specific CSS layer to maintain specificity control.
Sources: AGENTS.md:162-165, apps/reef/app/tests/architecture.test.ts:250-260
Key Wax Primitives
| Component | Usage Requirement |
|---|---|
CredentialInput | Must be used for all write-only credential entry to bypass router formData. |
DocumentSubmitButton | Required for all reloadDocument forms to provide local submission feedback. |
Table.useRowCursor | Enables keyboard navigation (↑, ↓, Enter) for table rows. |
HighlightedMatches | Used to bold text matches in filter fields consistently. |
Sources: apps/reef/app/tests/architecture.test.ts:108-115, AGENTS.md:148-154
Development and Validation
Reef includes an integrated testing harness called Reel for recording and reviewing browser-test scenarios.
Validation Gates
Before merging changes, developers must run the following checks:
npm run check: Lints and formats code.npm run typecheck: Validates TypeScript types.npm test: Runs Vitest units and architecture tests.npm run test:e2e: Executes Playwright-based browser scenarios (Reel).
Sources: apps/reef/README.md:120-130, apps/reef/e2e/README.md:10-20
Architecture Enforcement
Vitest architecture tests ensure that:
- Route modules are not imported into components.
- Components do not perform their own data fetching.
- Environment variables are only read at process bootstrap in
lib/runtime-config.server.ts. - Visual components in
waxhave associated Storybook stories.
Sources: apps/reef/app/tests/architecture.test.ts:200-210, apps/reef/app/tests/architecture.test.ts:300-315
Conclusion
Reef UI Frontend (Remix) provides a robust, type-safe interface for the Coral ecosystem. By enforcing strict boundaries between presentation and data, utilizing the Wax component library for consistent styling, and leveraging Reel for end-to-end validation, Reef ensures a reliable user experience across both web and desktop deployments.