Staff Engineer Architect v4.0

Staff Engineer Architect is an enterprise-grade AI system design tool that leverages the "Staff Engineer" meta-prompt framework to synthesize production-ready architecture artifacts. It bridges the gap between high-level intent and concrete technical implementation, enforcing AppSec governance and Reality Filters™ to mitigate LLM hallucinations.

🚀 Key Features

• AI Architecture Synthesis: Generates C4 diagrams, API contracts, and Terraform modules using Gemini 3 Pro.
• Reality Filters™: Pre-flight checks for Security, UX, and Brand compliance.
• Governance Console: Built-in content moderation queue and audit logging.
• Offline-First PWA: Workbox-powered hybrid caching for reliable access in zero-connectivity zones.
• Identity Management: Role-based onboarding and mock enterprise authentication flows.

🛠 Tech Stack

• Frontend: React 19, TypeScript, Tailwind CSS
• AI Engine: Google Gemini API (@google/genai)
• PWA: Workbox v6, Service Worker
• Icons: Lucide React
• Build: Vite 6

⚡ Quick Start

Prerequisites

• Node.js v20+ (see .nvmrc)
• Google Cloud API Key (Gemini)

Installation

1. Clone the repository

   git clone https://github.com/Krosebrook/INT-SysDesignGen.git
   cd INT-SysDesignGen
   

2. Install dependencies

   npm install
   

3. Configure Environment Copy the example env file and add your API key:

   cp .env.example .env
   # Edit .env and set GEMINI_API_KEY=your_google_gemini_api_key_here
   

4. Start Development Server

   npm run dev
   

   App runs at http://localhost:3000.

📦 Deployment

This is a static SPA built with Vite. The GEMINI_API_KEY is embedded in the client bundle at build time — set it as an environment variable in your deployment platform before building.

Local Build & Preview

# Type-check + build
npm run smoke

# Preview production build locally
npm run preview
# Then open http://localhost:4173

Deploy to Vercel

1. Import repository in Vercel Dashboard
2. Set environment variable: GEMINI_API_KEY = your Gemini key
3. Vercel auto-detects settings from vercel.json:
   • Build Command: npm run build
   • Output Directory: dist
   • Install Command: npm install
4. Click Deploy. SPA routing and security headers are configured automatically.

CLI deployment:

npx vercel --prod

Deploy to Cloudflare Pages

1. Connect repository in Cloudflare Pages Dashboard
2. Set environment variable: GEMINI_API_KEY = your Gemini key (in Pages > Settings > Environment variables)
3. Configure build settings:
   • Build Command: npm run build
   • Build Output Directory: dist
   • Node.js version: 20
4. Click Save and Deploy. SPA routing is handled by Cloudflare Pages' automatic SPA mode.

CLI deployment (Wrangler):

npx wrangler pages deploy dist --project-name se-architect

Environment Variables (Both Platforms)

Variable	Description	Required
GEMINI_API_KEY	Google Gemini API key for AI synthesis	Yes

Security note: Restrict your Gemini API key to your deployed domain using HTTP referrer restrictions in Google Cloud Console.

🔍 Deployment Smoke Check

Run this locally before pushing to production:

# Full smoke check: typecheck + build
npm run smoke

# Verify build output
ls dist/          # Should show: index.html, sw.js, assets/

# Local preview
npm run preview   # Opens http://localhost:4173
# Verify: app loads, login screen appears, no console errors

🧪 Testing

There are two distinct smoke checks:

• npm run smoke — build smoke check: runs TypeScript type-checking, builds the project, and validates the dist/ output (checks for index.html, sw.js, and non-empty assets/).
• smokeCheck() utility — content smoke check: validates that AI-generated architecture output contains required sections (Executive Summary, Audit Report, Quality Gates). Import it in your own test runner:

import { smokeCheck } from './tests/smoke.test.ts';
const result = await smokeCheck(generatedContent);
console.log(`Audit Score: ${result.score}%`);

📚 Documentation

Detailed documentation is available in the /docs directory:

• Architecture Overview
• Security Posture
• API Reference
• Local Database Schema
• Runbook
• Deployment Guide
• Observability

🤝 Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Generated by Staff Engineer Architect Core Team