damiansire/genai-fullstack-blueprint
damiansire/genai-fullstack-blueprint has 93 GitHub stars and 2 forks. GitHot measured 0 stars in 24 hours, 0 in 7 days, and 0 in 15 days. Last checked 2026-11-15 19:33 UTC. Last push 2026-09-24.
Measured star growth
- in 24h
- 0
- in 7 days
- 0
- in 15 days
- 0
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Full-stack reference architecture for multimodal GenAI apps: Angular client plus Node.js/Express AI Gateway, as a TypeScript monorepo.
AIREADME.md
Original🚀 Full-Stack Multimodal AI Application: A Reference Blueprint
This repository is a reference blueprint (a scaffold to build on, not a turnkey product) for modern, scalable web applications using a cutting-edge tech stack: Angular for the frontend, Node.js for the backend, and Google Gemini API for multimodal AI capabilities.
The project is built from the ground up following strict industry best practices for TypeScript full-stack development, focusing on maintainability, developer experience, and deployment readiness.
What CI verifies on every push — so "reference" never means "untested":
- Typecheck, lint, and formatting across both workspaces.
- The test suites of both workspaces. Backend: the
node:testsuite (184 tests), including HTTP integration tests that boot the real gateway on an ephemeral port and drive the whole chain end-to-end: health probes, the fail-closed auth boundary, andauth → rate-limit → token-limit → safety → handler. Frontend: the Vitest suite (67 tests) covering the client's domain layer: SSE parsing/cancellation inAiStreamService, frame-paced streaming render, JSON-Schema-to-form generation, the API-key interceptor boundary, and the route table. Component-template rendering and browser E2E are not in CI (see ADR 0004). Both counts are generated byscripts/update-metrics.mjs; CI runs it with--checkand fails on any drift, so a stale or hand-typed number cannot ship. - The Angular production bundle compiles.
- The entire Docker Compose stack (API + client) builds from its Dockerfiles and boots to healthy, with its live endpoints smoke-tested. That smoke test is a real, runnable script:
scripts/smoke.shbrings up the stack (docker compose up -d --build --wait) and curls every declared endpoint, failing if any is unhealthy; CI runs that same script on every push, and you can run it locally withbash scripts/smoke.sh.
What it deliberately does not claim: a hosted deployment with an SLA, or a formal penetration test / adversarial fuzzing pass — those are layers you add on top of this foundation. It does include a measured load burst, a sustained soak test, and a basic boundary threat model (see docs/load-test.md), plus a scoped security review of credential logging, rate limiting, multimodal input validation, and prompt-injection detection (see SECURITY.md).
🏗️ Architecture: Patterns and API reference live in
REGISTRY.md. The reasoning behind the load-bearing decisions (why an Express gateway, what happens when Gemini fails or rate-limits, the SSE streaming strategy, and the declared limits of this scaffold) is recorded indocs/adr/.
🧱 Core Architectural Principles
The architecture is designed around several key principles to ensure robustness and scalability:
🧩 Monorepo with npm Workspaces
Frontend and backend coexist in a single repository but are managed as independent packages. This simplifies dependency management and scripting while maintaining a clear separation of concerns.
🔗 Decoupled Architecture
The Angular client and Node.js server are completely independent applications communicating through a well-defined RESTful API. Each can be developed, tested, and deployed autonomously.
🧠 Layered Backend
The Node.js API follows a layered structure (Routes → Controllers → Services), cleanly separating HTTP request handling from business logic. This improves organization, testability, and reasoning about the codebase.
⚙️ Feature-Oriented Frontend
The Angular app abandons NgModules in favor of a 100% Standalone Component architecture. The folder structure is organized by features, not file type, grouping related code together for better modularity.
🧰 Tech Stack Overview
| Area | Technology | Description |
|---|---|---|
| Frontend | Angular 22 | Modern framework for building UIs using Standalone Components, Signal Forms, Signals for state management, and ChangeDetectionStrategy.OnPush for optimal performance. |
| Backend | Node.js v22+ | Uses "Built-in over dependencies" strategy: native SQLite, Worker Threads for CPU tasks, fetch API, and native test runner. |
| Express.js | Minimalist framework for building RESTful APIs. | |
| Multer | Middleware for handling file uploads (multipart/form-data). | |
| AI | Google Gemini | API for multimodal (text and image) content generation. |
| Language | TypeScript | Used end-to-end for strict typing and better developer experience. |
| Deployment | Docker & Nginx | Containerization for consistent and isolated deployments. Nginx serves the production Angular app as a high-performance web server. |
⚡ Getting Started
Follow these steps to set up and run the project locally.
Prerequisites
Make sure you have the following installed:
- Node.js (v22 or higher) and npm
- Angular CLI (
npm install -g @angular/cli) - Docker and Docker Compose (optional)
Installation and Configuration
Clone the repository:
git clone https://github.com/damiansire/genai-fullstack-blueprint.git
cd genai-fullstack-blueprint
Create your environment file by copying the example:
cp env.example .env
Edit .env and add your Google Gemini API key:
GEMINI_API_KEY=YOUR_API_KEY_HERE
Get your Gemini API key here: https://aistudio.google.com/app/apikey
Note: The Gemini API key is required for the Image Generation (Nano Banana) feature. Without it, you can still use the Text Generation and Image OCR features in demo mode.
Install dependencies (npm Workspaces will handle both frontend and backend):
npm install
Running the Application
Option 1: Development Mode (Recommended for development)
npm run dev
- Angular frontend: http://localhost:4200
- Node.js backend: http://localhost:3000
Option 2: Docker Mode (Recommended for production/testing)
# Start Docker Desktop first (macOS)
open -a Docker
# Build and run with Docker
docker compose up --build -d
# Check service status
docker compose ps
# View logs
docker compose logs -f
- Angular frontend: http://localhost:8080
- Node.js backend: http://localhost:3000
Health Checks:
curl http://localhost:3000/health/live # API liveness (also: /health/ready)
curl http://localhost:8080/health # Frontend (nginx)
Troubleshooting Docker: Refer to
REGISTRY.mdfor current deployment architectures and known edge cases.
🌟 AI Features
This platform includes three powerful AI capabilities powered by Google's models:
📝 Multi-Tiered Generation & Generative UI
- Routing across the plugins that ship today: three Google model plugins (
google-text-bison,gemini-image-gen,google-vision-ocr) plus a second real provider, OpenAI (openai-chat,openai-gpt-4o-mini). Every plugin implements the sameIModelStrategyport (seedomain/ai/strategy.interface.ts) — that port is the provider abstraction, not a separate interface. When a provider's circuit breaker opens,InvokeModelUseCaseautomatically falls back into the next provider inFALLBACK_MODEL_CHAIN(default:openai-gpt-4o-mini, then the local SLM slotllama-3.1-8b). The OpenAI adapter is unit-tested against a mockedfetch; end-to-end verification against the real OpenAI API is pending anOPENAI_API_KEY(seeenv.example). Routing to other frontier models (e.g. Claude 3.5 Sonnet) is still on the roadmap. - Server-Driven Generative UI: Angular dynamically renders visual components via
@deferbased on LLM Tool Calls. - Iterative Refinement (RCI): Recursive generation and quality scoring in worker threads.
- Token usage tracking and real-time streaming via SSE.
🔍 Image OCR (Google Vision OCR)
- Extract text from images (accuracy depends on the upstream Vision model and input quality)
- Multi-language support (whatever the upstream Vision API recognizes)
- Bounding box detection for text positioning
- Confidence scores for each annotation
- Supports JPEG, PNG, GIF, WEBP, BMP formats
🎨 Image Generation - Nano Banana (Gemini 2.5 Flash Image)
NEW! Generate and edit images using Gemini's native image generation:
Modes:
- Text-to-Image: Create images from descriptive prompts
- Image Editing: Modify existing images with text instructions
- Style Transfer: Apply artistic styles to photos
- Multi-Image Composition: Combine elements from multiple images
- Iterative Refinement: Conversational image editing
Capabilities:
- Multiple aspect ratios (Square, Portrait, Landscape, Widescreen, etc.)
- High-fidelity text rendering in images (logos, diagrams, posters)
- Photorealistic rendering with advanced lighting and camera controls
- Illustration and sticker generation
- Product mockups and commercial photography
- Sequential art (comic panels, storyboards)
Prompting Best Practices:
- Describe scenes narratively, not just keywords
- Use photography terms for realism (lens type, lighting, camera angle)
- Be hyper-specific about details
- Iterate conversationally for refinement
- Use step-by-step instructions for complex scenes
Note: All generated images include a SynthID watermark.
🏢 Enterprise AI Platform Capabilities
Beyond a bare starter, this scaffold wires up the patterns a B2B SaaS AI platform needs, so you extend and harden them instead of starting from scratch. Each item below is a reference implementation with its current maturity called out — not a turnkey guarantee:
🧠 Integrated RAG Infrastructure (Retrieval-Augmented Generation)
- Chat with Private Data: Seamlessly ingest and query private documents and customer databases without the prohibitive cost of fine-tuning models.
- Native Vector DB (optional, off by default): Designed to use the
sqlite-vecextension for in-memory semantic search.sqlite-vecis not a bundled dependency: it must be provided as an external SQLite extension at runtime. If it is not loadable, the database logsSemantic vector search disabledand only the exact-match (SHA-256) cache path operates. - Dynamic Context Injection: Automatically enriches LLM prompts with relevant semantic context to reduce hallucinations.
🛡️ Guardrails & AI Safety Firewall
- Prompt Injection Heuristic: Pre-flight validation of user inputs via a basic keyword/substring check. (A local SLM such as Phi-3.5 running in a background Worker Thread is on the roadmap — not yet implemented.)
- PII Masking: Automatic detection and masking of Personally Identifiable Information (emails, credit cards) before data leaves your infrastructure to reach public APIs.
- Toxicity Filters: A hook to actively block inappropriate or non-compliant generations, so you can enforce brand-safety policies at the gateway.
📊 Comprehensive LLMOps & Observability
- ROI & Billing Visibility: Granular tracking of Token Consumption and Latency (TTFT) per user and per tenant, essential for B2B billing models.
- Distributed Tracing: Uses Node.js
AsyncLocalStorageand native OTLP telemetry to trace every interaction from the HTTP request down to the SQLite vector cache and the LLM API call. - Low-Cost Caching: The exact-match cache (SHA-256 of the prompt) serves identical repeat queries locally, with no provider call and no token cost. The semantic (paraphrase-tolerant) path requires the optional
sqlite-vecextension and is off by default; without it, paraphrased queries are not cache hits.
🏢 Multi-Tenant Architecture (design, not yet implemented)
⚠️ Roadmap, not shipped. The codebase authenticates by API key only; there is no JWT verification, no per-tenant binding, and no data segregation by
tenant_idyet. Do not rely on this for compliance — the items below describe the intended design.
- Tenant Isolation (planned): The architecture is intended to bind tenant IDs to JWTs and segregate all contextual data (RAG vectors, chat histories, token budgets) per tenant. Implementing this binding and per-tenant query scoping is a prerequisite before any GDPR/HIPAA claim can be made.
- Tier-Based RBAC (partial):
rbacmiddleware can gate models by tier, but the tier is not yet populated from a real identity source, so every request currently resolves to the most restrictive (free) tier.
🗂️ Project Structure
Optimized for scalability and clarity:
/genai-fullstack-blueprint/
├── packages/ # Monorepo packages
│ ├── client/ # Angular 22 Application
│ │ ├── src/app/
│ │ │ ├── core/ # Singleton services, DI tokens
│ │ │ ├── shared/ # Reusable components (file-upload, navigation)
│ │ │ └── features/ # Functional components (text-model, image-model)
│ │ └── package.json
│ └── api/ # Node.js API (Clean Architecture)
│ ├── src/
│ │ ├── api/ # Routes, controllers, middleware
│ │ ├── application/ # Use cases (business logic orchestration)
│ │ ├── domain/ # Domain models (AI)
│ │ ├── infrastructure/ # DB, HTTP, rate-limit, workers, semantic cache, MCP
│ │ ├── services/ # Embedding, PII masking
│ │ ├── core/ # Base classes (ApiError, UseCase), circuit-breaker, config
│ │ └── plugins/ # AI model strategies (google-text-bison, gemini-image-gen, google-vision-ocr, openai-chat)
│ └── package.json
├── .docker/ # Dockerfiles for production
│ ├── Dockerfile.client # Angular + Nginx
│ ├── Dockerfile.server # Node.js API
│ └── nginx.conf # Nginx configuration
├── REGISTRY.md # Master Architectural Registry (Decisions & Patterns)
├── package.json # Workspace configuration
├── package-lock.json # Dependency lock file
├── env.example # Environment variables template (copy to .env)
└── docker-compose.yml # Container orchestration
✅ Best Practices Implemented
Backend (Node.js)
- Secure API Key Handling: All secrets are managed via environment variables — never hardcoded.
- File Uploads:
multerconfigured per route to efficiently and securely handle multipart/form-data. - Strict CORS Policy: Only trusted origins are allowed in production.
Frontend (Angular 22)
- 100% Standalone Components: No NgModules — less boilerplate, simpler dependency management.
- Signal Forms: Uses Angular's
form()/FormFieldAPI from@angular/forms/signalsfor type-safe, model-driven forms. - Reactive State with Signals: Uses
signal(),computed(), andhttpResource()for high-performance state management. - Zoneless Change Detection: Runs without
zone.jsviaprovideZonelessChangeDetection()for smaller bundles and better performance. - OnPush Change Detection: All components use
ChangeDetectionStrategy.OnPush. - Vitest Test Runner: Unit tests run with Vitest via
@angular/build:unit-testfor fast, modern testing. - Design Tokens: Centralized CSS custom properties in
:rootfor consistent theming across components. - Accessibility (ARIA): Decorative emojis wrapped in
aria-hidden, form inputs witharia-invalid/aria-describedby, spinners withrole="status". - Lazy Loading with
loadComponent: Reduces initial bundle size and improves performance. - Modern Dependency Injection: Uses
inject()withInjectionTokenfor API configuration. - Native Control Flow: Leverages
@if,@for, and@switchsyntax for cleaner, faster templates.
📚 Documentation
- Architecture Decision Records (docs/adr/) - Why the gateway exists, how provider failure/rate-limiting is handled, the streaming strategy, and the declared limits of the scaffold.
- Master Architectural Registry (REGISTRY.md) - API references, setup workflow, component structures, and Node.js native patterns.
- SECURITY.md - Scoped security review. docs/load-test.md - Measured load numbers. docs/deployment.md - Deployment guide.
🐳 Production Deployment with Docker
The project is fully containerized and ready for production deployment.
- Multi-stage Builds: Each Dockerfile separates build and runtime environments for smaller, secure images.
- Workspace Support: Dockerfiles are configured for npm workspaces (monorepo architecture)
- Nginx for Frontend: The built Angular app is served via an optimized Nginx container for SPA delivery.
- Health Checks: Both services include health check endpoints for monitoring
- Single Command Orchestration: The
docker-compose.ymlfile spins up the full production stack easily.
To build and run production containers:
# Start Docker Desktop first (macOS)
open -a Docker
# Build and run all services
docker compose build
docker compose up -d
# Check status (both services should be healthy)
docker compose ps
# View logs
docker compose logs -f
# Stop services
docker compose down
Useful Commands:
# Rebuild without cache
docker compose build --no-cache
# Build specific service
docker compose build api
docker compose build client
# View service logs
docker compose logs -f api
docker compose logs -f client
# Execute commands in running container
docker compose exec api sh
docker compose exec client sh
Architecture Notes:
- The API service uses a multi-stage build with TypeScript compilation
- Dependencies are installed using
npm ci --workspacefor monorepo support - Production TypeScript configuration relaxes strictness for deployment
- Nginx serves the Angular app with SPA routing support and compression
For detailed orchestration and operational guidelines, refer to the REGISTRY.md.
🤝 Contributing
Contributions, suggestions, and improvements are welcome!
Feel free to open a pull request or issue if you'd like to help enhance this blueprint.