Feature/onboarding improvements

[djankies]

Pull Request

👋🏻 Hey, thanks for putting this together! Thought this might be a nice feature. It's a big PR but it's one cohesive feature and a sizeable portion is just tests. I tried to document changes the best I could. Happy to modify. 😄

Summary

This PR implements a database initialization system for Archon, providing a more streamlined onboarding experience for users. The feature automatically detects when database tables are missing and guides users through the setup process with an interactive UI component.

---

---

Changes made

Onboarding and Setup Improvements

• Added database status detection and automatic redirection to onboarding when tables are missing (archon-ui-main/src/components/layouts/MainLayout.tsx, archon-ui-main/src/pages/OnboardingPage.tsx)
• Created interactive DatabaseSetupStep component with auto-verification polling (archon-ui-main/src/components/onboarding/DatabaseSetupStep.tsx)
• Updated onboarding flow to dynamically adjust steps based on database setup requirements (archon-ui-main/src/pages/OnboardingPage.tsx)

[!NOTE] See below for complete changes

Backend API Implementation

• Implemented database API endpoints for status, setup SQL, and verification (python/src/server/api_routes/database_api.py)
• Added database configuration management with environment variable support (python/src/server/config/config.py)
• Enhanced credential service integration with graceful error handling (python/src/server/services/credential_service.py)

Error Handling and Logging

• Introduced structured error classes for database and network errors, with remediation guidance (archon-ui-main/src/types/errors.ts)
• Added structured logging utility with correlation ID support (archon-ui-main/src/utils/logger.ts)
• Implemented database exception hierarchy for backend operations (python/src/server/services/database_exceptions.py)

Settings Context and UI Improvements

• Refactored SettingsContext to use stable reference for refreshSettings method (archon-ui-main/src/contexts/SettingsContext.tsx)
• Added new spin-twice animation for loading indicators (archon-ui-main/src/index.css)

Documentation and Infrastructure

• Updated README to reflect new onboarding flow with database setup requirements (README.md)
• Enhanced Vitest configuration for improved test file inclusion (archon-ui-main/vitest.config.ts)
• Updated Docker Compose configuration for better service management (docker-compose.yml)

Local Supabase Instance Support

• Added support for local Supabase instances with adaptive UI behavior (archon-ui-main/src/components/onboarding/DatabaseSetupStep.tsx)
• Updated documentation to include local instance guidance (README.md)

Test Coverage

• Added frontend test coverage for database setup functionality (archon-ui-main/test/components/onboarding/DatabaseSetupStep.test.tsx, archon-ui-main/test/services/databaseService.test.ts, archon-ui-main/test/components/layouts/MainLayout.test.tsx)
• Implemented backend test suite for database API (python/tests/test_database_api.py)
• Created test utilities and fixtures for database testing (python/tests/utils/database_test_utils.py, python/tests/fixtures/database_fixtures.py)

Type of Change

• [x] New feature (non-breaking change which adds functionality)
• [ ] Bug fix (non-breaking change which fixes an issue)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Documentation update
• [ ] Performance improvement
• [ ] Code refactoring

Affected Services

• [x] Frontend (React UI)
• [x] Server (FastAPI backend)
• [ ] MCP Server (Model Context Protocol)
• [ ] Agents (PydanticAI service)
• [x] Database (migrations/schema)
• [x] Docker/Infrastructure
• [x] Documentation site

Testing

• [x] All existing tests pass
• [x] Added new tests for new functionality
• [x] Manually tested affected user flows
• [x] Docker builds succeed for all services

Test Evidence

# Frontend tests - Database feature specific
cd archon-ui-main && npx vitest run test/components/onboarding/DatabaseSetupStep.test.tsx test/services/databaseService.test.ts test/components/layouts/MainLayout.test.tsx
# Result: 25/25 tests passing
# Note: 3 pre-existing tests failed in other files not related to this PR and were confirmed to fail on main branch, before changes were made

Test Files  3 passed (3)
Tests       25 passed (25)
Duration    732ms

Coverage for database setup feature:

File	% Stmts	% Branch	% Funcs	% Lines
src/components/layouts/MainLayout.tsx	91.13	77.14	75	91.13
src/components/onboarding/DatabaseSetupStep.tsx	75.39	76	20	75.39
src/services/databaseService.ts	77.41	51.42	100	77.41
src/types/errors.ts	88.31	100	83.33	88.31
src/utils/logger.ts	88.88	80	71.42	88.88

# Backend tests
cd python && uv run pytest tests/test_database_api.py
# Result: 40/40 tests passing

Python coverage for database API implementation:

File	% Coverage	Uncovered
src/server/api_routes/database_api.py	86%	17 lines uncovered
src/server/services/database_exceptions.py	87%	7 lines uncovered
src/server/config/config.py	33%	64 lines uncovered (general config, not all database-specific)
src/server/services/credential_service.py	18%	260 lines uncovered (broader service, database setup uses small subset)

Checklist

• [x] My code follows the service architecture patterns
• [x] If using an AI coding assistant, I used the CLAUDE.md rules
• [x] I have added tests that prove my fix/feature works
• [x] All new and existing tests pass locally
• [x] My changes generate no new warnings
• [x] I have updated relevant documentation
• [x] I have verified no regressions in existing features

Breaking Changes

None. This is a purely additive feature that enhances the onboarding experience without affecting existing functionality.

Additional Notes

• The feature includes configurable timeout via VITE_DB_SETUP_TIMEOUT_MS for testing
• Auto-verification polling occurs every 3 seconds with a 3-minute timeout
• Graceful degradation when Supabase credentials are missing
• Error handling with correlation IDs for debugging

---

Technical Implementation Details

🏗️ Architecture Overview

Onboarding System Flow

flowchart TD
    Start([User Opens App]) --> EnvCheck{Environment Variables<br/>Configured?}
    EnvCheck -->|No| EnvError[Show Configuration Required<br/>Cannot Proceed]
    EnvCheck -->|Yes| Check{Database Status Check}
    Check -->|Tables Exist| CredCheck{Credentials<br/>Configured?}
    Check -->|Tables Missing| Redirect[Redirect to /onboarding]
    Redirect --> Display[Display DatabaseSetupStep]
    Display --> Copy[User Copies SQL]
    Copy --> OpenEditor[User Opens Supabase Editor]
    OpenEditor --> Run[User Runs SQL in Supabase]
    Run --> Poll{Auto-Verification<br/>Every 3 seconds}
    Poll -->|Not Ready| Timeout{3 minutes<br/>elapsed?}
    Timeout -->|No| Poll
    Timeout -->|Yes| Manual[Show Manual Check Button]
    Manual --> ManualCheck[User Clicks Check Now]
    ManualCheck --> Poll
    Poll -->|Success| DbComplete[Database Setup Complete]
    DbComplete --> CredCheck
    CredCheck -->|No| ProviderStep[Show Provider Setup]
    CredCheck -->|Yes| Complete[Onboarding Complete]
    ProviderStep --> Complete
    Complete --> Continue[Continue to App]

Onboarding Sequence Diagram

sequenceDiagram
    participant User
    participant Frontend as React Frontend
    participant Backend as FastAPI Backend
    participant DB as Supabase Database
    participant Editor as Supabase SQL Editor

    Note over User,Editor: Initial App Load
    User->>Frontend: Opens application
    Frontend->>Backend: GET /api/database/status
    Backend->>DB: Check table existence
    DB-->>Backend: Tables missing
    Backend-->>Frontend: {setup_required: true}
    Frontend->>Frontend: Redirect to /onboarding

    Note over User,Editor: Database Setup Step
    Frontend->>Backend: GET /api/database/setup-sql
    Backend-->>Frontend: SQL content + project_id
    Frontend->>User: Display DatabaseSetupStep UI
    User->>Frontend: Click "Copy SQL"
    Frontend->>User: Show "Copied!" confirmation
    User->>Frontend: Click "Open Supabase Editor"
    Frontend->>Editor: Open SQL Editor with pre-filled URL

    Note over User,Editor: SQL Execution
    User->>Editor: Paste and execute SQL
    Editor->>DB: Create tables and data
    DB-->>Editor: Tables created successfully

    Note over User,Editor: Auto-Verification Loop
    loop Every 3 seconds (up to 3 minutes)
        Frontend->>Backend: POST /api/database/verify-setup
        Backend->>DB: Check table existence
        DB-->>Backend: Tables status
        Backend-->>Frontend: Verification result
        alt Tables not ready
            Frontend->>Frontend: Continue polling
        else Tables ready
            Frontend->>Frontend: Proceed to next step
        end
    end

    Note over User,Editor: Timeout Fallback
    alt Timeout reached
        Frontend->>User: Show "Check Now" button
        User->>Frontend: Click "Check Now"
        Frontend->>Backend: POST /api/database/verify-setup
        Backend->>DB: Check table existence
        DB-->>Backend: Tables exist
        Backend-->>Frontend: {tables_exist: true}
    end

    Note over User,Editor: Completion
    Frontend->>Frontend: Mark database setup complete
    Frontend->>Frontend: Proceed to provider setup
    Frontend->>User: Show provider configuration step

📝 Implementation Details by File

Frontend Implementation

archon-ui-main/src/components/layouts/MainLayout.tsx

• Added database status check before credential validation
• Integrated databaseService for setup detection
• Modified onboarding redirect logic to prioritize database setup
• Added sessionStorage-based detection for onboarding transitions

Test Coverage: 91.13% statements - 11/11 tests passing

• Test File: test/components/layouts/MainLayout.test.tsx (NEW)
• Validates: Health check functionality, Onboarding redirect logic, Error handling, Integration with database and credential services

---

archon-ui-main/src/components/onboarding/DatabaseSetupStep.tsx (NEW)

• React component that guides users through database initialization
• Auto-verification polling every 3 seconds
• 3-minute timeout after which polling stops and manual check button appears
• Configurable timeout via VITE_DB_SETUP_TIMEOUT_MS environment variable for manual testing
• Displays step progress indicators with completion states
• Provides SQL copy functionality with confirmation and user feedback for failures
• Generates Supabase SQL editor URLs based on SUPABASE_URL environment variable
• Environment variable handling - shows configuration guidance when missing
• Structured Logging: Uses structured logger with correlation IDs for debugging
• Toast Integration: Provides user feedback for clipboard copy failures

Test Coverage: 75.39% statements - 7/7 tests passing

• Test File: test/components/onboarding/DatabaseSetupStep.test.tsx (NEW)
• Validates: Initial loading and rendering states, Database status detection and appropriate UI rendering, Auto-verification polling mechanism, Manual verification capabilities, Error handling for network failures, Environment variable configuration guidance, Proper cleanup of timers and resources, Callback handling for completion and skipping

---

archon-ui-main/src/pages/OnboardingPage.tsx

• Modified onboarding flow to integrate database setup step
• Updated step progression logic to handle database setup completion
• Updated welcome message to include database setup guidance

---

archon-ui-main/src/services/databaseService.ts (NEW)

• Singleton pattern with structured logging and correlation ID support
• Logging with correlation IDs for request tracing
• Error Handling:
  • DatabaseError: Base error class with context preservation
  • DatabaseConnectionError: Infrastructure failures (500s)
  • DatabaseConfigurationError: Configuration issues (400s)
  • NetworkError: Network connectivity problems
• Three Core Methods with Distinct Responsibilities:
  • getStatus() (GET): Idempotent status check, no side effects, used for frequent polling and initial detection
  • getSetupSQL() (GET): Retrieve initialization SQL with project metadata and editor URLs
  • verifySetup() (POST): State-changing verification of database setup that clears credential cache when tables detected, used during setup completion

Test Coverage: 77.41% statements - 7/7 tests passing

• Test File: test/services/databaseService.test.ts
• Validates: Singleton pattern implementation, Error handling for network and server failures, JSON parsing resilience, Response handling with missing or extra fields, Complete database setup flow verification

Backend Implementation

python/src/server/api_routes/database_api.py (NEW)

• GET /api/database/status: Returns initialization state with environment variable validation, no side effects
• GET /api/database/setup-sql: Provides SQL content with fallback mechanism and Supabase editor URL generation
• POST /api/database/verify-setup: State-changing verification endpoint - Validates table creation AND clears credential cache when successful
• All endpoints verify Supabase configuration before database operations
• Error responses with correlation IDs for debugging in alpha development
• Uses default SQL file (/app/migration/complete_setup.sql) with optional override via DATABASE_SETUP_SQL_PATH environment variable.
• Supabase URL Parsing: Extracts project ID from SUPABASE_URL environment variable for direct SQL editor links
• verify-setup endpoint clears credential cache to ensure fresh state after table creation
• Logging with correlation IDs and error context
• ARCHON_SIMULATE_DB_STATE environment variable support for testing different database states without actual Supabase instances:
  • CONNECTION_ERROR: Simulates database connection failures with localhost URL detection
  • MISSING_ENV: Simulates missing environment variables scenario
  • SETUP_REQUIRED: Simulates database requiring initialization
  • READY: Simulates properly initialized database

Test Coverage: 86% statements - 40/40 tests passing

• Test File: tests/test_database_api.py
• Validates: All endpoints, SQL delivery, URL parsing, cache invalidation, error scenarios

---

python/src/server/main.py

• Registered database router in FastAPI application
• Added global _database_initialized flag and tracking function
• Enhanced credential initialization with graceful error handling
• Added database configuration status logging
• Updated server startup to run in limited mode when database unavailable

Test Coverage: Covered through API endpoint tests

---

python/src/server/services/credential_service.py

Implementation:

• Added is_supabase_configured() method for environment variable validation
• Enhanced _get_supabase_client() to return None for missing env vars (graceful degradation)
• Updated load_all_credentials() with comprehensive error handling
• Added database connectivity checks in all credential operations
• Implemented graceful fallback to empty credentials when database unavailable
• Enhanced logging for database configuration status
• Integration with structured error types for proper error context

Test Coverage: Exception handling tested through API integration tests

New Supporting Files

archon-ui-main/src/types/errors.ts (NEW)

• Structured error type definitions for database operations
• DatabaseError, DatabaseConnectionError, DatabaseConfigurationError, NetworkError
• Error context preservation with correlation IDs and remediation guidance
• TypeScript interfaces for consistent error handling across the frontend

archon-ui-main/src/utils/logger.ts (NEW)

• Structured logging utility with correlation ID support
• Consistent log formatting across all frontend components
• Logger factory pattern with component-specific instances
• Context preservation and structured error reporting

python/src/server/config/config.py (45+ lines added)

• Added DatabaseConfig class for configurable database settings
• load_database_config() function supporting environment variable configuration
• Support for DATABASE_SETUP_SQL_PATH, DATABASE_SETUP_TIMEOUT
• Configuration-driven approach replacing hardcoded paths

python/src/server/services/database_exceptions.py (NEW)

• Structured exception hierarchy for database operations
• DatabaseError, DatabaseConnectionError, DatabaseConfigurationError, DatabaseNotInitializedException
• Context gathering and diagnostic information preservation
• Integration with alpha development error reporting principles

Test Fixes and Quality Improvements

archon-ui-main/test/setup.ts (8 lines added)

• Added global console.error filtering to suppress expected ONBOARDING_CHECK_FAILED error messages during test runs
• These errors are intentionally triggered by MainLayout error handling tests to verify proper error behavior

archon-ui-main/test/pages.test.tsx (1 line modified)

• Fixed encrypted credential test data to include required encrypted_value field
• The test for "OpenAI API key is encrypted" was failing because the mock credential object was missing the actual encrypted value
• Added encrypted_value: 'encrypted_key_value' to properly simulate a valid encrypted credential
• Required by isLmConfigured function validation logic which requires both is_encrypted: true AND a non-null encrypted_value

Configuration Updates

archon-ui-main/vitest.config.ts

• Added test files to the existing include array

🧪 Test Commands

Run All Tests

cd archon-ui-main &&
npx vitest run test/components/onboarding/DatabaseSetupStep.test.tsx test/services/databaseService.test.ts test/components/layouts/MainLayout.test.tsx --reporter=dot
cd ..

cd python &&
uv run pytest tests/test_database_api.py -v &&
cd ..

✅ Manual Verification Steps

1. Missing Environment Variables Test - Should handle missing environment variables gracefully and redirect to onboarding

Run the following commands:

docker-compose down &&
export SUPABASE_URL= && 
export SUPABASE_SERVICE_KEY= &&
docker-compose up -d
unset SUPABASE_URL
unset SUPABASE_SERVICE_KEY

Open browser to http://localhost:3737

Expected Behavior:

• [ ] App redirects to /onboarding
• [ ] Shows "Supabase Configuration Required" step
• [ ] Displays clear instructions with .env code block
• [ ] Shows link to Supabase Dashboard (https://supabase.com/dashboard)
• [ ] Message shows "Database configuration is required to continue"

2. Fresh Installation Test (After Environment Setup)

Create a new Supabase project (no tables) and add correct environment variables to .env:

SUPABASE_URL=https://your-new-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key-here
# SUPABASE_URL=https://your-existing-project.supabase.co
# SUPABASE_SERVICE_KEY=your-existing-service-key-here

Or using environment variables without modifying .env:

docker-compose down &&
export SUPABASE_URL=https://your-new-project.supabase.co &&
export SUPABASE_SERVICE_KEY=your-service-key-here &&
docker-compose up -d
unset SUPABASE_URL
unset SUPABASE_SERVICE_KEY

Open browser to http://localhost:3737

Expected Behavior:

• [ ] App detects missing tables and shows DatabaseSetupStep
• [ ] Copy SQL button works and shows "Copied!" confirmation
• [ ] Step 1 indicator animates and shows checkmark
• [ ] "Open Editor" button generates and opens correct Supabase project in the browser
• [ ] Step 2 indicator animates when editor opened

3. Test Auto-Verification

• [ ] Component shows "Waiting for you to run the SQL..." with spinner animation when no tables are detected
• [ ] Auto-verification polls every 3 seconds (check network tab & log level=verbose)
• [ ] Once SQL is run in Supabase, app automatically proceeds to next step

3a. Test Polling Timeout

Run RESET_DB.sql to reset the database

docker-compose down &&
export VITE_DB_SETUP_TIMEOUT_MS=6001 &&
docker-compose up -d
unset VITE_DB_SETUP_TIMEOUT_MS

[!note] The timeout is set to 6001ms here to ensure polling is triggered twice. Anything below this will cause 1 polling test failure. Default value is 3 minutes (180000ms)

Expected Behavior:

• [ ] Timeout occurs after configured duration
• [ ] Manual "Check Now" button displays after timeout
• [ ] Polling ceases after timeout (check network tab and logs (level=verbose))
• [ ] Check now displays "Not Ready" when clicked while tables are not detected
• [ ] When tables are detected, "Check Now" button enables next step

4. Existing Database Test

Reset environment variables to a project with tables already created:

SUPABASE_URL=https://your-existing-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key-here

docker-compose down && docker-compose up -d

Open browser to http://localhost:3737

Expected Behavior:

• [ ] App detects existing tables
• [ ] Skips database setup step entirely
• [ ] Proceeds to normal onboarding flow

5. Local Supabase Instance Testing

Test with a local Supabase instance to verify adaptive UI behavior:

# Set up local Supabase URL
docker-compose down &&
export SUPABASE_URL=http://localhost:54321 &&
export SUPABASE_SERVICE_KEY=your-local-service-key &&
docker-compose up -d

Open browser to http://localhost:3737

Expected Behavior:

• [ ] App detects local instance (no sql_editor_url in response)
• [ ] DatabaseSetupStep shows modified instructions: "Open your local Supabase Studio and run the SQL in the SQL Editor tab"
• [ ] "Open Editor" button is hidden (not displayed)
• [ ] Copy SQL button still works normally
• [ ] Auto-verification polling still functions correctly
• [ ] Manual verification works when SQL is run in local Studio

5a. Database State Simulation Testing

ARCHON_SIMULATE_DB_STATE environment variable can be used to simulate different database states for testing UI states in isolation.

# Test connection error with localhost URL detection
docker-compose down &&
export SUPABASE_URL=http://localhost:54321 &&
export SUPABASE_SERVICE_KEY=fake-key-for-testing &&
export ARCHON_SIMULATE_DB_STATE=CONNECTION_ERROR &&
docker-compose up -d

# Test missing environment variables
docker-compose down &&
export ARCHON_SIMULATE_DB_STATE=MISSING_ENV &&
docker-compose up -d

# Test setup required state
docker-compose down &&
export SUPABASE_URL=https://test.supabase.co &&
export SUPABASE_SERVICE_KEY=fake-key-for-testing &&
export ARCHON_SIMULATE_DB_STATE=SETUP_REQUIRED &&
docker-compose up -d

# Test setup required state (local)
docker-compose down &&
export SUPABASE_URL=http://localhost:54321 &&
export SUPABASE_SERVICE_KEY=fake-key-for-testing &&
export ARCHON_SIMULATE_DB_STATE=SETUP_REQUIRED &&
docker-compose up -d

# Test ready state (skip database setup)
docker-compose down &&
export SUPABASE_URL=https://test.supabase.co &&
export SUPABASE_SERVICE_KEY=fake-key-for-testing &&
export ARCHON_SIMULATE_DB_STATE=READY &&
docker-compose up -d

# Disable simulation (normal operation)
docker-compose down &&
unset ARCHON_SIMULATE_DB_STATE &&
docker-compose up -d

Expected Behavior:

• [ ] CONNECTION_ERROR: Shows improved error handling with localhost detection and Docker networking guidance
• [ ] MISSING_ENV: Displays environment variable configuration screen
• [ ] SETUP_REQUIRED: Shows normal database setup flow with SQL instructions
• [ ] READY: Skips database setup entirely, proceeds to next onboarding step
• [ ] Error messages are user-friendly with actionable guidance instead of technical details

6. API Endpoint Testing

# Check status endpoint
curl http://localhost:8181/api/database/status | jq '.'

# Get setup SQL
curl http://localhost:8181/api/database/setup-sql | jq '.' | sed 's/\\n/\n/g'

# Verify setup (POST)
curl -X POST http://localhost:8181/api/database/verify-setup | jq '.'

📦 Dependencies

No new production dependencies added.

📚 Documentation Updates

Updated README.md with new database setup instructions

Summary by CodeRabbit

• New Features

  • Guided onboarding at /onboarding with a new Database Setup step (copy/run SQL, open editor, auto‑verify + manual “Check Now”), updated step numbering and clearer progress.
  • Onboarding now checks DB readiness and LLM config, shows toasts, and advances users through start services.

• Documentation

  • Unified Quick Start, detailed Database Reset workflow (full reset warning: deletes all data), simulated DB states for testing, and listed core services/ports.

• UI

  • Improved startup health-check behavior and a subtle new spin-twice animation (respects reduced‑motion).

• Tests

  • Extensive new UI and API tests covering onboarding, DB setup, and verification flows.

• Chores

  • docker-compose additions: DB simulation env var and migration mount; frontend DB setup timeout env var.

[coderabbitai[bot]]

Walkthrough

Adds a complete database onboarding and verification flow: frontend UI DatabaseSetupStep, health-check and onboarding gating changes, new databaseService, structured errors and logger, backend /api/database endpoints and config, credential service diagnostics and state APIs, docker/test env flags, and extensive JS/Python tests and fixtures.

Changes

Cohort / File(s)	Summary
Docs & DevOps README.md, docker-compose.yml	Centralizes onboarding in README, documents DB reset/testing and onboarding URL, adds ARCHON_SIMULATE_DB_STATE and VITE_DB_SETUP_TIMEOUT_MS envs, mounts ./migration into server, and tweaks server command formatting.
Frontend: Layout & Onboarding archon-ui-main/src/components/layouts/MainLayout.tsx, archon-ui-main/src/pages/OnboardingPage.tsx, archon-ui-main/src/components/onboarding/DatabaseSetupStep.tsx	Adds DB status gating to health/onboarding checks, increases retries, per-check AbortController timeouts and timeout cleanup, redirects to /onboarding when DB/setup/API keys missing, and implements DatabaseSetupStep with copy/open-editor actions, auto/manual verification polling, timeout fallback, error handling, and timer cleanup.
Frontend: Service, Types & Logger archon-ui-main/src/services/databaseService.ts, archon-ui-main/src/types/errors.ts, archon-ui-main/src/utils/logger.ts	New DatabaseService singleton (getStatus/getSetupSQL/verifySetup) with timeouts, correlation-aware logging and rich error parsing; introduces DatabaseError family and ErrorContext types; adds structured Logger and createLogger utility with correlationId helpers.
Frontend: Settings & Styles archon-ui-main/src/contexts/SettingsContext.tsx, archon-ui-main/src/index.css	Stabilizes loadSettings and refreshSettings with useCallback, adds optimistic setProjectsEnabled; adds spin-twice keyframes and .animate-spin-twice utility with prefers-reduced-motion support.
Frontend Tests & Fixtures archon-ui-main/test/** archon-ui-main/vitest.config.ts	Adds/updates tests: MainLayout.test.tsx, DatabaseSetupStep.test.tsx, services/databaseService.test.ts; extensive JS fixtures (test/fixtures/database-fixtures.ts), test setup overrides (setup.ts), and registers tests in Vitest config.
Backend: API, Config & Main python/src/server/api_routes/database_api.py, python/src/server/config/config.py, python/src/server/main.py	New /api/database router (GET /status, GET /setup-sql, POST /verify-setup) with simulation support and correlation logging; DatabaseConfig loader and env-based timeout/path; wires router into main app and tracks database initialization state.
Backend: Credential Service & Exceptions python/src/server/services/credential_service.py, python/src/server/services/database_exceptions.py	Makes Supabase client optional, adds is_supabase_configured, cache/inspect/reset methods, safer credential operations when unconfigured, richer diagnostics and correlation_id handling; introduces server-side DatabaseError family, DatabaseNotInitializedException, and gather_diagnostic_context.
Backend Tests & Utilities (Python) python/tests/**	Adds extensive Python tests and fixtures: test_database_api.py, python tests fixtures (python/tests/fixtures/database_fixtures.py), and utilities (python/tests/utils/database_test_utils.py) covering status, setup-sql, verify flows, errors, and integration scenarios.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant UI as Frontend UI
  participant FEsvc as databaseService (FE)
  participant API as FastAPI /api/database
  participant Cred as credential_service

  rect rgba(200,230,255,0.18)
  Note over UI: App start or route change
  UI->>FEsvc: getStatus()
  FEsvc->>API: GET /status
  API->>Cred: is_supabase_configured() / load_all_credentials()
  Cred-->>API: config/state (tables exist / missing)
  API-->>FEsvc: {initialized, setup_required, message}
  FEsvc-->>UI: status
  end

  alt setup_required
    UI->>FEsvc: getSetupSQL()
    FEsvc->>API: GET /setup-sql
    API-->>FEsvc: {sql_content, project_id, sql_editor_url}
    FEsvc-->>UI: show setup SQL
    loop auto-verify (poll, timeout)
      UI->>FEsvc: verifySetup()
      FEsvc->>API: POST /verify-setup
      API->>Cred: reset_cache()/load_all_credentials()
      API-->>FEsvc: {success, message, correlation_id}
      FEsvc-->>UI: verification result
    end
  else ready
    Note over UI: proceed with provider/API-key steps
  end

sequenceDiagram
  autonumber
  participant Client as Tests / FE
  participant API as FastAPI /api/database
  participant FS as FileSystem
  participant Cfg as load_database_config()

  rect rgba(255,245,220,0.14)
  Note over API: GET /setup-sql handling
  API->>Cfg: load_database_config()
  API->>FS: read setup_sql_path
  FS-->>API: sql_content or error
  API-->>Client: {sql_content, project_id?, sql_editor_url?} or error
  end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Poem

I nibble keys beneath the moon,
Spin-twice ears hum a setup tune.
SQL crumbs scattered in a row,
Polls ping back—"ready" they show.
Hop, click, verify—onboarding grows! 🐇✨

[!TIP]

🔌 Remote MCP (Model Context Protocol) integration is now available!

Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats.

✨ Finishing Touches

🧪 Generate unit tests

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coleam00]

Thanks for this PR @djankies! We aren't ready to make changes to the onboarding flow right now but will be soon and I'll have this PR in mind!

[djankies]

@coleam00 No worries man. #338 and this PR have a lot of similar changes so this feature can definitley make use of some of that code if #338 is merged first. Let me know when/if you guys get around to onboarding stuff and I'm happy to refactor. 😄

[Wirasm]

The Frontend is undergoing migration, please feel free to reopen this following the new architecture if you want to

Thank you for this contribution! @djankies