Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/KingPsychopath/oooc-fete-finder/llms.txt

Use this file to discover all available pages before exploring further.

OOOC Fête Finder supports three data modes controlled by the DATA_MODE environment variable. Each mode determines the primary source and fallback chain for live event reads.

​
Available modes

​
Remote mode

Value: DATA_MODE=remote Default: Yes (when DATA_MODE is unset in development) Recommended for: Production and preview deployments Remote mode uses a two-tier source chain with automatic fallback:
  1. Primary: Postgres event store (managed via admin)
  2. Fallback: Local CSV file (data/events.csv) if Postgres is unavailable
Remote mode is the required mode for Vercel preview and production deployments. Missing or invalid DATA_MODE in these environments triggers a startup failure.
Source priority: When to use:
  • Production deployments with Postgres configured
  • Environments where admin-managed content is the source of truth
  • Applications requiring real-time event updates via admin panel
Requirements:
  • DATABASE_URL must be configured for Postgres reads
  • Local CSV file (data/events.csv) should exist as a fallback safety net
Fallback behavior: If the Postgres store is unavailable or returns no data, the application automatically falls back to the local CSV and adds a warning:
“Managed store unavailable; serving local CSV fallback (stale-safe mode).”
This ensures the site remains functional even during database outages, though the data may be stale.

​
Local mode

Value: DATA_MODE=local Recommended for: Local development without Postgres Local mode reads events exclusively from the local CSV file at data/events.csv. Source priority: When to use:
  • Local development without a Postgres connection
  • Testing with a static dataset
  • Environments where admin-managed content is not needed
Requirements:
  • data/events.csv must exist and contain valid event data
Behavior:
  • No Postgres connection required
  • No fallback chain (local CSV is the only source)
  • Coordinate population is disabled by default in local mode
Local mode should not be used in production. It does not support admin content management or real-time updates.

​
Test mode

Value: DATA_MODE=test Recommended for: Automated testing and CI/CD pipelines Test mode uses in-memory static data from data/events.ts without reading files or databases. Source priority: When to use:
  • Automated tests (Jest, Playwright, etc.)
  • CI/CD environments without database access
  • Development scenarios requiring deterministic test data
Behavior:
  • No file reads
  • No database connections
  • Instant data availability (no I/O)
  • Deterministic and reproducible results
Test mode is ideal for integration and E2E tests where you need predictable event data without external dependencies.

​
Mode comparison

FeatureRemoteLocalTest
Primary sourcePostgres storeLocal CSVIn-memory data
Fallback sourceLocal CSVNoneNone
Admin management✅ Yes❌ No❌ No
Requires DATABASE_URL✅ Yes❌ No❌ No
Coordinate population✅ Enabled❌ DisabledN/A
Real-time updates✅ Yes❌ No❌ No
Stale-safe fallback✅ Yes❌ No❌ No
Production use✅ Required❌ Not recommended❌ Not recommended

​
Data flow in remote mode

Remote mode follows this detailed flow:
  1. Request initiated: Server component or API route calls DataManager.getEventsData()
  2. Try Postgres store:
    • Query LocalEventStore.getCsv() for event sheet data
    • Process CSV data with processCSVData()
    • Hydrate event keys and validate data
    • Populate coordinates from KV cache (if geocoding enabled)
  3. On Postgres success: Return events with source "store"
  4. On Postgres failure:
    • Log failure reason
    • Attempt local CSV fallback at data/events.csv
  5. On local CSV success: Return events with source "local" and stale-safe warning
  6. On both failures: Return empty data with error messages
Coordinate population in remote mode is durable and KV-backed (maps:locations:v1). Coordinates are prewarmed on admin writes to reduce live geocoding churn.

​
Runtime validation

All modes validate event data after loading:
  • Row count check: Must return at least 1 event
  • Schema validation: Events must match the Event type
  • Required fields: Each event must have Event Key, Venue, etc.
If validation fails, the source is skipped and the next fallback is attempted (in remote mode) or an error is returned (in local/test modes).

​
Configuration examples

# .env.production
DATA_MODE=remote
DATABASE_URL=postgresql://user:pass@host:5432/dbname?sslmode=require
AUTH_SECRET=<generate-secret>
ADMIN_KEY=<generate-key>
This configuration uses Postgres as the primary source with local CSV as a stale-safe fallback.
# .env.local
DATA_MODE=local
AUTH_SECRET=<generate-secret>
This configuration reads events from data/events.csv without requiring Postgres.
# .env.test
DATA_MODE=test
AUTH_SECRET=test-secret-minimum-32-characters-long
This configuration uses in-memory test data for fast, deterministic tests.

​
Switching modes

To switch data modes:
  1. Update DATA_MODE in your .env file or deployment platform
  2. Restart the development server or redeploy
  3. Verify the mode in admin at /admin/operations → Data Store Status
The active data mode and current source are displayed in the startup banner and in the admin Operations panel.

​
Production requirements

In Vercel preview or production environments:
  • DATA_MODE must be explicitly set
  • DATA_MODE must be one of: remote, local, or test
  • Missing or invalid DATA_MODE causes immediate startup failure
Recommended production value: DATA_MODE=remote

​
Troubleshooting

Error message:
Missing required DATA_MODE in production. Set DATA_MODE to remote, local, or test.
Solution: Add DATA_MODE=remote to your production environment variables and redeploy.
Warning message:
Managed store unavailable; serving local CSV fallback (stale-safe mode).
Possible causes:
  • DATABASE_URL not configured
  • Postgres connection failure
  • Event store tables not initialized
Solution:
  1. Verify DATABASE_URL is set correctly
  2. Run pnpm bootstrap:postgres-store to seed the event store
  3. Check database connectivity with pnpm health:check
Error message:
Local CSV fallback failed: [specific error]
Possible causes:
  • data/events.csv does not exist
  • CSV file is empty or malformed
  • CSV headers do not match expected schema
Solution:
  1. Verify data/events.csv exists in the project root
  2. Check CSV headers match the expected schema
  3. Ensure at least one valid event row exists

Build docs developers (and LLMs) love

Get started for freeTalk to us