ADR 001: Neon Database + Stack Auth Integration for Monitor Application

Status: Proposed → SupersededDate: 2025-10-22 Deciders: Engineering Team Context: Monitor application needs persistent storage and authentication Superseded By: 2025-12-21-unified-auth-provider-abstraction

Note: This ADR has been superseded. The neon_auth.users_sync approach is Neon-specific and does not work with Cloud SQL. See the Unified Auth Provider Abstraction ADR for the GCP-compatible replacement.

Context and Problem Statement

The monitor application currently operates without persistent storage or authentication. We need to add:

1. Database persistence for monitoring data, machine states, job history, and metrics
2. User authentication to secure access to the monitoring interface
3. Multi-tenant support to isolate monitoring data by organization/team

We have existing Neon database infrastructure and Stack Auth configuration already in the ENV system.

Decision Drivers

• Existing Infrastructure: Neon databases already configured (DEV, STAGING, PROD, TEST)
• Pre-configured Auth: Stack Auth environment variables already in config/environments/components/auth.env
• Serverless Architecture: Neon's serverless Postgres aligns with our distributed worker model
• Zero Additional Setup: Both services already provisioned and configured
• Automatic User Sync: Neon Auth automatically syncs user profiles to neon_auth.users_sync table

Considered Options

Option 1: Neon + Stack Auth (Neon Auth) ✅ SELECTED

• Leverage existing Neon database infrastructure
• Use pre-configured Stack Auth credentials
• Automatic user sync via Neon Auth integration
• Row-level security (RLS) for multi-tenant isolation

Option 2: Build custom auth on Neon

• Requires implementing auth from scratch
• No automatic user sync
• More maintenance overhead

Option 3: Use different auth provider (Auth0, Clerk, etc.)

• Requires new service configuration
• Additional cost and complexity
• No integration with existing setup

Decision Outcome

Chosen option: Option 1 - Neon + Stack Auth (Neon Auth)

Positive Consequences

• ✅ Zero infrastructure setup required (already configured)
• ✅ Automatic user profile sync to database
• ✅ JWT-based authentication with local verification
• ✅ Row-level security for data isolation
• ✅ Serverless scaling aligned with worker architecture
• ✅ Consistent with existing ENV system architecture

Negative Consequences

• ⚠️ Dependency on Neon's Stack Auth integration
• ⚠️ Migration effort if we need to change auth providers later

Technical Details

Environment Variables (Already Configured)

From config/environments/components/auth.env:

NEXT_PUBLIC_STACK_PROJECT_ID=2dd79195-ac90-44a7-af26-cf83abb53623
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=pck_522rb12qj8d7scykqb7h9ga7t1cn2fgap5av14tx8m6br
STACK_SECRET_SERVER_KEY=${SECRET_STACK_SECRET_SERVER_KEY}

From .env.secrets.local:

SECRET_STACK_SECRET_SERVER_KEY=ssk_q3fash1g1jte7y5t9f8qypbp9x6p4tyweg551h7x3cyt0
DATABASE_BASE_URL_DEV=postgresql://postgres:npg_fuMwsrJiI7d0@ep-orange-boat-afkxlijp-pooler.c-2.us-west-2.aws.neon.tech

Database Schema Strategy

1. User Authentication: Via neon_auth.users_sync table (auto-managed by Neon Auth)
2. Application Data: Custom schema with RLS policies
3. Multi-tenancy: Row-level security based on authenticated user

Authentication Flow

1. User signs in via Stack Auth UI components
2. JWT issued by Stack Auth
3. Frontend includes JWT in API requests
4. Backend verifies JWT locally (via JWKS)
5. Database queries filtered by user via RLS

Key Integration Points

• Frontend: @stackframe/stack React SDK
• Backend: JWT verification via jose library
• Database: Neon serverless driver @neondatabase/serverless
• User Sync: Automatic via Neon Auth integration API

Implementation Notes

Monitor Service Interface

The monitor application will need a service interface definition:

• Database connection (from component-level ENV)
• Stack Auth SDK configuration
• API endpoints for authenticated operations

Database Migrations

• Use Prisma or raw SQL migrations
• Set up RLS policies for multi-tenant isolation
• Create application-specific tables (machines, jobs, metrics)

Security Considerations

• All database queries must use authenticated connection
• RLS policies enforce data isolation
• JWT verification on every request
• No sensitive data in client-side metadata

Pros and Cons of the Options

Neon + Stack Auth ✅

Good:

• Leverages existing, configured infrastructure
• Automatic user synchronization
• Built-in RLS and security
• Serverless scaling
• Low operational overhead

Bad:

• Platform lock-in to Neon Auth
• Limited to Stack Auth's feature set

Custom Auth

Good:

• Full control over auth logic
• No third-party dependencies

Bad:

• Significant development time
• Ongoing maintenance burden
• Security implementation risk
• No automatic user sync

Alternative Auth Provider

Good:

• Might offer more features
• Provider-specific ecosystem

Bad:

• Requires new service setup
• Additional costs
• Not integrated with Neon
• Manual user sync required

Links and References

• Neon Stack Auth Documentation
• Stack Auth Documentation
• Stack Auth SDK (@stackframe/stack)
• Neon Serverless Driver
• Context7 MCP library documentation accessed 2025-10-22

Next Steps

See implementation plan: docs/plans/neon-stack-auth-monitor-implementation.md