Skip to main content

Athena Helm — Full-Stack GitOps & Sandbox Manual 🔌🦉

Welcome to the Athena Helm Full-Stack GitOps & Sandbox replication guide. This document provides clear, GitOps-driven, step-by-step instructions to recreate our database schemas, deploy security rules, and seed invited beta users. This ensures 100% reproducibility across all staging and production environments.

📡 1. Architecture Overview (Private Beta Gate)​

To balance rapid front-end prototyping with production-grade security, Athena Helm gates all coordinate, telemetry, and developer spec features using a real-time cloud Firebase Firestore & Auth backend:

  +-----------------------------------------------------------+
  |                   1. Firebase Auth                        |
  |             (Verified Skipper Credentials)                |
  +-----------------------------------------------------------+
                               |
                               v
  +-----------------------------------------------------------+
  |              2. Firestore: beta_invitations               |
  |         (Keyed by Email address - Read-Only for Users)    |
  +-----------------------------------------------------------+
                               |
                               v
  +-----------------------------------------------------------+
  |              3. Firestore: subscribers                    |
  |     (Profile details & capability tier e.g. 'Developer')  |
  +-----------------------------------------------------------+

Collection Schemas​

  1. beta_invitations:

    • Document ID: The invited skipper's email address (e.g. captain@athena-helm.com).
    • Fields:
      • invited: true (boolean)
      • plan: "Developer" | "Ocean Voyager" | "Coastal Cruiser" | "Day Sailer" (string)
      • timestamp: ISO String (string)
    • Security Policy: Anyone can query a single document by ID to check their whitelist status (get), but only the verified administrator can list (list) or edit (write) them.

  2. subscribers:

    • Document ID: The user's authenticated email address.
    • Fields:
      • email: User email (string)
      • plan: Active capability tier (string)
      • timestamp: ISO String (string)
    • Security Policy: Users can only read (get) their own profile if authenticated, and all client-side updates to the plan field are forbidden. Plan modifications must be updated via administrative seed scripts, Stripe webhooks, or the Firebase Console.

🛡️ 2. Deploying Firestore Security Rules (GitOps)​

Our security rules reside in the root of the repository at firestore.rules. Tracking this file in Git ensures that any changes to our security postures are fully audited and version-controlled.

To deploy or update rules directly from the CLI:

  1. Ensure the Firebase CLI is installed in your terminal environment.
  2. Authenticate with your Firebase account (use the --reauth flag if your local cached token is expired): 
    npx -y firebase-tools@latest login --reauth
  3. Deploy the local firestore.rules file directly to your target database instance: 
    npx -y firebase-tools@latest deploy --only firestore:ai-studio-24ce5aa0-23b7-44e4-8387-d0a407575828 --project gen-lang-client-0346222639

This command parses, compiles, and applies the local security rules onto the live Google Cloud Firestore named database instance instantly.

🌱 3. Database Seeding & Registry Automation​

To avoid manual, error-prone data injection via the Google Cloud UI console, we provide a Git-tracked, administrative script at scripts/seed-invitations.ts to bulk-load whitelisted emails directly from the CLI.

Running the Seed Script​

To populate your database with initial beta invitations, execute the following command in the project root:

# Seed initial invitations into the live Firestore database
npx tsx scripts/seed-invitations.ts

Seeding Payload​

By default, the script seeds the following whitelisted skippers:

  • captain@athena-helm.com -> Pre-approved plan: Developer
  • benzwick@gmail.com -> Pre-approved plan: Developer

To invite new skippers, simply append their email and pre-assigned plan to the array inside scripts/seed-invitations.ts and re-run the script.

🛠️ 4. Environment Replication Checklist​

To set up a fresh developer environment from scratch:

  1. Create a new project in the Firebase Console.
  2. Enable Firestore Database and Authentication (enable Email/Password and Google Sign-In providers).
  3. Copy your project's Web App configuration keys and save them to the project root as firebase-applet-config.json.
  4. Run the GitOps rules deployment directly to your named database ID: 
    npx -y firebase-tools@latest deploy --only firestore:[YOUR_NAMED_DATABASE_ID] --project [YOUR_PROJECT_ID]
  5. Run the seed automation: 
    npx tsx scripts/seed-invitations.ts
  6. Start the local server: 
    npm run dev

You are now fully configured with a production-grade secure sandbox environment.