Genstack Web SDK

Genstack is a modular, scalable web SDK and backend platform for managing AI model providers, projects, and tracks, with a focus on extensibility, security, and real-time data synchronization. It leverages FastAPI, Firebase, Firestore, Redis, and modern frontend technologies to deliver a robust SaaS foundation for AI-driven applications.

---

Table of Contents

• Architecture Overview
• Core Features
• Backend Stack
• Frontend Stack
• API Structure
• Data Model
• Caching & Realtime
• Deployment & CI/CD
• Development & Usage
• Security & Best Practices

---

Architecture Overview

Genstack is organized as a modern SaaS platform with clear separation of concerns:

• Backend: FastAPI application, modular API versioning, Firestore for persistent storage, Redis (Upstash) for caching, and Firebase Functions for real-time triggers.
• Frontend: Jinja2 templating, modular static assets (JS/CSS), and Alpine.js for reactive UI.
• Cloud Functions: Python-based Firebase Functions for cache synchronization and event-driven logic.

Directory highlights:

• app/ — Main FastAPI app, API routes, business logic, templates, static assets
• functions/ — Firebase Functions for cache and event handling
• schemas/ — JSON schemas for data validation and structure
• test/ — Test scripts for core logic

---

Core Features

• Project & Track Management: Users can create isolated projects, each with multiple tracks (e.g., LLMs, tools, etc.).
• Provider Integration: Plug-and-play support for AI providers (OpenAI, Google, Anthropic, etc.), with encrypted API key management.
• Model Management: Add, remove, and monitor models per track, with usage and failure tracking.
• Plan & Billing Logic: Support for multiple plans (basic, pro, custom) and credit-based usage.
• Real-time Sync: Firestore triggers update Redis caches for low-latency access and analytics.
• Role-based Access: Admin and user separation, with secure endpoints and privilege checks.
• Search: Algolia integration for model discovery.

---

Backend Stack

• FastAPI: Main web framework for API and server-side rendering
• Firebase Admin SDK: Authentication and Firestore database access
• Firestore: Hierarchical, document-based storage for users, projects, tracks, and models
• Redis (Upstash): Caching layer for fast access to provider keys, track stats, and more
• Algolia: Model search and discovery
• Cloud Functions (Python): Event-driven cache updates and business logic
• Async & Security: Async endpoints, Fernet encryption for sensitive data

Key Backend Modules

• app/api/v1/routes/ — RESTful API endpoints (user, sdk, model, admin)
• app/database/firestore/ — Firestore data access and manipulation
• app/providers/ — Provider abstraction and integration logic
• app/utils/ — Utility functions (auth, key generation, plan selection, etc.)
• functions/cache/ — Redis cache management for providers, keys, tracks

---

Frontend Stack

• Jinja2: Server-side HTML templating
• Alpine.js: Lightweight reactivity for UI components
• Tailwind CSS: Utility-first styling
• Vanilla JS: Modular scripts for project, track, and admin UIs
• Firebase Auth (Frontend): Google and GitHub OAuth integration

UI Structure

• app/templates/ — Modular, reusable HTML templates (base, components, project, admin, etc.)
• app/static/ — Static assets (CSS, JS, images)
• Responsive Design: Mobile-first layouts, dynamic modals, and navigation

---

API Structure

• Versioned API: All endpoints under /api/v1/
• RESTful Design: CRUD for projects, tracks, models, providers
• Authentication: JWT via Firebase Auth, with user verification on all sensitive endpoints
• Admin Endpoints: Restricted routes for model/provider management
• SDK Endpoints: For backend-to-backend integration

Example endpoints:

• GET /api/v1/user/get-projects — List user projects
• POST /api/v1/model/get-models — List models for a track
• POST /api/v1/sdk/get-providers — List available providers for a project
• POST /api/v1/admin/add-model — Add a new model (admin only)

---

Data Model

• User: Authenticated via Firebase, owns multiple projects
• Project: Contains metadata, billing, API keys, and model providers
• Track: Sub-resource of project, contains models, usage stats, and config
• Provider: Abstraction for AI/ML model providers (OpenAI, Google, etc.)
• Cache: Redis keys for fast lookup of provider keys, track stats, etc.

Firestore hierarchy:

users/{uid}/projects/{project_id}/tracks/{track_id}

Example project document:

{
  "projectName": "Test Project",
  "createdAt": "2025-12-12T00:00:00.000Z",
  "billing": [],
  "apiKeys": ["ENCRYPTED_KEY_1", "ENCRYPTED_KEY_2"],
  "modelProviders": { ... }
}

---

Caching & Realtime

• Redis (Upstash): Used for caching provider keys, track stats, and reducing Firestore reads
• Firebase Functions: Listen to Firestore changes and update Redis cache accordingly
• Cache Keys: Structured as uid:project-id:track-id for track stats, uid:project-id:provider-id for provider keys
• Track Stats: API calls, failures, and model usage are cached for analytics and quota enforcement

---

Deployment & CI/CD

• Docker: Containerized for consistent deployment
• GitHub Actions: CI pipeline for linting, type-checking, and tests (.github/workflows/ci.yml)
• Firebase Hosting/Functions: For serverless backend and real-time triggers
• Environment Management: .env files for secrets, not committed to source
• Run Locally:
  • Windows: ./runserver.bat [development|production]
  • Mac/Linux: ./runserver.sh

---

Development & Usage

1. Clone the repo & install dependencies
2. Set up environment variables (.env)
3. Run the server (see above)
4. Access the app at http://localhost:8000
5. API docs available at /docs (FastAPI auto-generated)

---

Security & Best Practices

• Sensitive Data: All API keys and credentials are encrypted (Fernet)
• Role Checks: Admin endpoints require explicit privilege
• Input Validation: All API endpoints validate input and handle errors gracefully
• CI/CD: Automated checks for type safety and code quality
• No Secrets in VCS: All secrets managed via environment variables and CI secrets

---

License

Proprietary. All rights reserved.