AGENTS.md

This project ships agent context: skills under .agents/skills/ and MCP servers in .mcp.json. Load them before writing code.

Project

This is an introductory React sample demonstrating basic Rayfin data operations without authentication or storage. It serves as a minimal starting point for understanding Rayfin's data layer with React.

Architecture

This sample uses React with Vite. The main application logic lives in src/App.tsx with React hooks for state management.

Key components:

• App component – Main React component managing timestamps state and UI
• RayfinClient<AppSchema> – Type-safe Rayfin client initialized via useMemo

React hooks used:

• useState – Manages timestamps, loading, error, and status state
• useCallback – Memoizes refreshTimestamps and sendTimestamp functions
• useMemo – Creates singleton RayfinClient instance
• useEffect – Triggers initial data fetch and status auto-dismiss

Features demonstrated:

• Data creation via rayfinClient.data.Timestamp.create()
• Data querying via rayfinClient.data.Timestamp.select()
• Ordering and pagination with orderBy and first

Rayfin Integration Points

Decorators (@microsoft/rayfin-core):

• rayfin/data/Timestamp.ts – Timestamp entity with @entity(), @uuid(), @date(), and @role() decorators

Schema (rayfin/data/schema.ts):

• AppSchema type maps entity names to model types for type-safe client usage

Client (@microsoft/rayfin-client):

• RayfinClient<AppSchema> initialized in src/App.tsx with baseUrl and publishableKey

Data API (@microsoft/rayfin-data):

• Direct data operations through rayfinClient.data.Timestamp
• CRUD operations are type-safe and DAB-compliant

Rayfin Configuration

rayfin/rayfin.yml enables:

• Data: Enabled
• Auth: Disabled (uses @role('anonymous', '*') for open access)
• Storage: Disabled

Environment

Source of truth: rayfin/.env (RAYFIN_PUBLIC_* prefix). rayfin dev generates .env.local with Vite-compatible names before frontend startup.

Vite frontend variables (in .env.local):

• VITE_RAYFIN_API_URL – Rayfin backend URL (default http://localhost:5168); sourced from RAYFIN_PUBLIC_API_URL
• VITE_RAYFIN_PUBLISHABLE_KEY – Rayfin publishable key; sourced from RAYFIN_PUBLIC_PUBLISHABLE_KEY

Config files:

• .env – defaults for all environments
• .env.local – generated by rayfin dev (git-ignored)
• rayfin/.env – runtime and deployment values (git-ignored, managed by Rayfin CLI)

Generated and Do-Not-Edit Files

Do not edit these paths; treat them as build or local-state outputs:

• rayfin/.temp/ – Rayfin/DAB config generation output
• dist/ – Vite build output
• .env.local – local environment overrides (git-ignored)