Architecture, technology stack, tool implementation details, security design, infrastructure, and delivery specifications for the RealizeAI Value Micro-SaaS Platform. Delivered under a Build + Operate engagement with hosting-first pricing.
The RealizeAI Value platform follows a modern GCP-native architecture with a Next.js frontend on Cloud Run, Cloud SQL PostgreSQL backend with Row-Level Security, Firebase Auth, Stripe for payments, and a Vertex AI (Gemini 2.0 Flash) PDF generation pipeline. The architecture prioritizes a Form-Before-Download user flow with mandatory data capture for benchmarking, personalized output via maturity archetypes, and a 6-Category Hub navigation model (MVP: Categories 1-2, with Categories 3-6 visible as "Coming Soon").
Delivery Model: All architecture and integration work is led by John Lewis (Solutions Architect), augmented by BFI's 13-agent AI fleet. Agents handle code scaffolding, design system generation, QA automation, CI/CD, and documentation — enabling a 5-day delivery timeline for 20 tools that would traditionally require 24+ weeks with a 5-person team. See Volume I for the full delivery model and Volume III for detailed BOE.
Architecture Decisions: This volume reflects the Developer Brief requirements including: (1) 6-Category Hub navigation, (2) Form-Before-Download access model, (3) Vertex AI (Gemini 2.0 Flash) + Puppeteer PDF generation, (4) 20 MVP tools in Categories 1-2, and (5) RealizeAI brand design system (#1e3a5f, Garamond/Roboto).
Premium SPA with enterprise-grade UX
Managed PostgreSQL with row-level security
PCI-compliant checkout with Stripe (singles, bundles, annual)
AI-personalized premium reports
Auto-scaling cloud with global CDN
Full observability and transactional email
User Journey: Persona → Browse → Purchase → Form → PDF → Download
1. Persona Mirror → User self-selects persona (“I Need AI” / “My Pilot is Stuck” / “I’m Asked to Opine”) → recommended category highlighted
2. Category Hub → Cat 1 & 2 active (20 tools grouped by type); Cat 3-6 visible as "Coming Soon"
3. Add to Cart → Single tool ($97-197), Bundle A ($397, 5 tools), Bundle B ($697, all 20), or Annual ($997/yr)
4. Stripe Checkout → Payment processed → user account created/linked → confirmation email via SendGrid
5. Form Required (Non-Negotiable) → Mandatory assessment form: Org Name, Title, Revenue, Industry, AI Maturity Level, Use Case, Email
6. PDF Generation → Form data + tool_id → Vertex AI generates personalized content (archetype-specific) → Puppeteer renders HTML→PDF → stored in GCS
7. Delivery → Immediate download OR email delivery via SendGrid → cached PDF available for re-download without re-form
8. Benchmarking → Form data stored anonymized in form_responses table → aggregated for Phase 2 benchmarking dashboard
The core user interface features a Persona Mirror landing page with 3 self-select personas, leading to a 6-Category Hub. Categories 1-2 are fully active in MVP; Categories 3-6 are visible but locked with "Coming Soon" badges. Within each active category, tools are grouped by type (Scoring Tools, Templates, User Guides).
Persona Mirror: Three self-select persona cards (“I Know I Need AI But Don't Know How” / “My Pilot is Stuck” / “I'm Asked to Opine”) guide users to a recommended category. This is non-gating — users can browse all active categories regardless of persona selection. Persona data is stored for analytics.
Each of the 20 MVP tools falls into one of three implementation categories. Category determines the technical pattern, integrations, and output format.
| Category | Pattern | Input | Output | Complexity |
|---|---|---|---|---|
| Scoring Tool | React form → Cloud SQL → Score Engine → Vertex AI → Puppeteer PDF | 6–15 questions + archetype | Personalized multi-page branded PDF | High (3–5 days/tool) |
| User Guide | React accordion/tabs → Styled content (read-only) | None (downloadable) | Interactive web reference + downloadable PDF | Low (1–2 days/tool) |
| Template | React form → Template engine → Puppeteer PDF/Word | Structured form fields | Formatted PDF/Word/Excel | Medium (2–4 days/tool) |
The moment of truth. 15-min two-axis matrix diagnostic. Plot your organization into one of 4 zones: Tourist, Bureaucrat, Hazard, or Accelerator. 6 dimensions scored on 1–5 scale. Personalized PDF with zone-specific recommendations.
Exposes C-Suite perception gaps. Reinterprets diagnostic scores through Purposeful leadership, Profitable operations, and Pervasive execution lenses. Radar chart + gap analysis PDF.
Brutal honesty on legacy data cleanup: how much time and money before you can START a 90-day AI sprint. Cost estimation guide with downloadable framework.
| Tool | Type | Est. Days | Key Features |
|---|---|---|---|
| Master AI Initiative Charter (The Gateway) | Template | 3 | 30+ structured fields → boardroom-ready charter PDF |
| The 4 Laws Template | Template | 2 | Governance framework template |
| Scoping — The 3-Key Vault | Guide | 1.5 | Interactive scoping methodology guide |
| The 30 Pearls for a Pilot Project | Guide | 1.5 | Searchable best-practices catalog |
| Requirement Gathering Template | Template | 2 | Structured requirements capture + export |
| Master AI Risk Register | Template | 3 | Risk identification framework + Excel/PDF output |
| CFO Drift Mitigation Planner | Template | 3 | OpEx drift tracking + mitigation PDF |
| Macro YoY P&L Model | Template | 3.5 | Multi-tab financial model Excel/PDF |
| 90-Day Sprint RACI Matrix | Template | 2.5 | Role-based RACI matrix + exportable PDF |
| 90-Day Implementation Roadmap | Guide | 1.5 | Interactive sprint-by-sprint roadmap guide |
| Build vs. Buy Checklist | Guide | 1.5 | Decision framework with scoring |
| Procurement Red-Flag Checklist | Guide | 1.5 | Vendor evaluation red-flag interactive grid |
| Pilot Purgatory Extraction Audit | Scoring | 4 | "Kill or Scale" diagnostic with blocker analysis PDF |
| The Antibody Audit | Scoring | 4 | 12 questions → organizational resistance heatmap PDF |
Total MVP Implementation Effort: 20 AI-powered tools — 5 scoring tools + 15 templates & guides. With the agent-augmented model, this is delivered in 5 working days (40 hours) by one architect + 13 AI agents — see Volume III for the detailed Basis of Estimate.
| Table | Purpose | RLS Policy |
|---|---|---|
users | Profile: email, password_hash, name, created_at | auth.uid() = id |
categories | 6 content categories (name, slug, description, order) | Public read |
tools | 20 tools mapped to categories (name, type, description, price_min, price_max) | Public read |
bundles | Bundle definitions (name, description, price, discount_percent, tools[]) | Public read |
orders | Purchase records (user_id, bundle_id, total_price, status) | auth.uid() = user_id |
order_items | Line items per order (order_id, tool_id, price) | auth.uid() = orders.user_id |
form_responses | Mandatory assessment data (org, title, revenue, industry, maturity, use_case, email) | auth.uid() = user_id |
pdfs | Generated PDFs (user_id, tool_id, form_response_id, gcs_url, regenerated_count) | auth.uid() = user_id |
purchases | Stripe payment records, tool access grants | auth.uid() = user_id |
user_responses | Assessment inputs per tool per user | auth.uid() = user_id |
generated_reports | PDF metadata, GCS URLs, expiration dates | auth.uid() = user_id |
tool_feedback | Thumbs up/down + comments per tool | auth.uid() = user_id |
benchmarking_data | Anonymized aggregated responses (no PII) | Admin-only read |
organization_settings | Enterprise tier: team management, admin controls | auth.uid() = admin_id |
organization_members | Multi-seat user mapping for Enterprise tier | auth.uid() IN (admin, member) |
Gating is form-based, not credit-based. After Stripe checkout, a Cloud Run API function handles the access workflow:
1. Verify orders.status = 'paid' for user → 2. Present mandatory 7-field assessment form → 3. Validate + insert row in form_responses → 4. Trigger Vertex AI PDF generation → 5. Store PDF in GCS → 6. Return signed download URL
Form responses power the benchmarking data pipeline (anonymized, aggregated). Users who purchased bundles can access all tools in the bundle without re-purchasing.
Security is embedded at every layer — not bolted on post-development. This aligns with BFI's production security track record (2 OWASP sprints, 23 findings remediated) and the BRD's stringent data privacy requirements.
auth.uid() = user_id on every data table. User A cannot, under any circumstances, query User B's data. Pen-tested pre-launch.| Service | Purpose | Integration Method | Phase |
|---|---|---|---|
| Stripe | Payments, billing, subscriptions | Stripe.js + Webhooks to Cloud Run API | 1 |
| Cloud SQL | Managed PostgreSQL database | Cloud SQL Auth Proxy + connection pooling | 1 |
| Firebase Auth | Authentication (50K MAU free) | Firebase Admin SDK + client JS SDK | 1 |
| Vertex AI | AI-personalized PDF generation | Gemini 2.0 Flash REST API from Cloud Run | 1A |
| Cloud Storage (GCS) | PDF storage with signed URLs | GCS client library; signed download URLs | 1A |
| Cloud Armor | DDoS protection, WAF, bot mitigation | Cloud Armor security policy on HTTPS LB | 1A |
| SendGrid | Transactional + nurture emails | REST API from Cloud Run | 1B |
| PostHog | Product analytics, funnels, feature flags | PostHog JS SDK | 2 |
| Google Analytics 4 | Campaign attribution, UTM tracking | GA4 tag + GTM | 1 |
| Metric | Target | Approach |
|---|---|---|
| Page Load Time | < 2 seconds | CDN-served static assets; code splitting; lazy loading |
| PDF Generation | < 5 seconds | Pre-compiled templates; optimized chart rendering; async generation with loading state |
| Lighthouse Score | ≥ 90 | Image optimization; tree-shaking; minimal JS bundle; efficient CSS |
| Concurrent Users | 1,000+ simultaneous | Cloud SQL connection pooling; Cloud CDN caching; stateless Cloud Run containers |
| Database Queries | < 100ms p95 | Indexed columns; optimized RLS policies; connection pooling |
| Uptime SLA | 99.5% | Cloud Run managed uptime + Cloud Armor failover + Cloud Monitoring alerting |
Scalability Path: The Cloud Run + Cloud SQL + CDN architecture scales horizontally without code changes. Moving from 100 to 10,000 users requires only Cloud SQL plan upgrades and CDN cache tuning — zero architectural refactoring.
| Day | Focus | Deliverables | Milestone |
|---|---|---|---|
| Day 1 | Foundation | Cloud SQL schema (7+ tables + RLS), Stripe integration (singles, bundles, annual), RealizeAI design system, Firebase Auth flow, CI/CD pipeline, staging deploy | Foundation ready |
| Day 2 | Commerce + UX | Persona Mirror landing page, Category Hub (6 categories, 2 active), category detail pages, Form-Before-Download flow, cart/checkout, promo codes | User journey live |
| Day 3 | Scoring Tools + PDF Pipeline | Vertex AI PDF pipeline (Gemini → HTML → Puppeteer → GCS); TRM (scoring + zone classification); 3P Alignment Audit (15Q + radar); Pilot Purgatory Extraction; Swamp Draining Reality Check | PDF pipeline + 4 tools live |
| Day 4 | Templates, Guides & Remaining Tools | Antibody Audit (scoring); 15 templates & guides (batch pipeline build); SendGrid email integration; user dashboard; legal docs (TOS, Privacy, disclaimers) | All 20 tools functional |
| Day 5 | QA + Launch | Security audit (RLS pen-test, OWASP); E2E testing all 20 tools + all payment paths; book hub; production deployment + DNS + SSL + monitoring; client walkthrough + handoff | ⭐ Production Live |