{"id":51542813,"url":"https://github.com/damiansire/genai-fullstack-blueprint","last_synced_at":"2026-07-09T15:30:28.021Z","repository":{"id":318080077,"uuid":"1069928959","full_name":"damiansire/genai-fullstack-blueprint","owner":"damiansire","description":"Production-ready full-stack blueprint for building multimodal GenAI apps with an Angular client and Node.js/Express AI Gateway.","archived":false,"fork":false,"pushed_at":"2026-06-25T23:02:01.000Z","size":982,"stargazers_count":92,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-26T01:03:42.799Z","etag":null,"topics":["ai","ai-gateway","angular","blueprint","express","fullstack","gemini-api","generative-ai","monorepo","nodejs","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/damiansire.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-04T22:41:32.000Z","updated_at":"2026-06-25T23:15:45.000Z","dependencies_parsed_at":"2025-10-05T00:23:00.406Z","dependency_job_id":"33ed3038-dc10-44d5-8d7d-ddbbf52cc72a","html_url":"https://github.com/damiansire/genai-fullstack-blueprint","commit_stats":null,"previous_names":["damiansire/genai-scaffold"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/damiansire/genai-fullstack-blueprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiansire%2Fgenai-fullstack-blueprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiansire%2Fgenai-fullstack-blueprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiansire%2Fgenai-fullstack-blueprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiansire%2Fgenai-fullstack-blueprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/damiansire","download_url":"https://codeload.github.com/damiansire/genai-fullstack-blueprint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/damiansire%2Fgenai-fullstack-blueprint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35304874,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-gateway","angular","blueprint","express","fullstack","gemini-api","generative-ai","monorepo","nodejs","typescript"],"created_at":"2026-07-09T15:30:25.396Z","updated_at":"2026-07-09T15:30:28.012Z","avatar_url":"https://github.com/damiansire.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# 🚀 Full-Stack Multimodal AI Application: A Production Blueprint\n\nThis repository serves as a **production-ready blueprint** for building modern, scalable, and high-performance 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.\n\nThe 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**.\n\n---\n\n\u003e **🏗️ Architecture:** All architectural decisions and documentation are centrally maintained in `REGISTRY.md`.\n\n## 🧱 Core Architectural Principles\n\nThe architecture is designed around several key principles to ensure robustness and scalability:\n\n### 🧩 Monorepo with npm Workspaces\n\nFrontend 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.\n\n### 🔗 Decoupled Architecture\n\nThe 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.\n\n### 🧠 Layered Backend\n\nThe 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.\n\n### ⚙️ Feature-Oriented Frontend\n\nThe 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.\n\n---\n\n## 🧰 Tech Stack Overview\n\n| Area           | Technology         | Description                                                                                                                                                |\n| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Frontend**   | **Angular 21**     | Modern framework for building UIs using Standalone Components, Signal Forms, Signals for state management, and `ChangeDetectionStrategy.OnPush` for optimal performance. |\n| **Backend**    | **Node.js v22+**   | Uses \"Built-in over dependencies\" strategy: native SQLite, Worker Threads for CPU tasks, `fetch` API, and native test runner.                              |\n|                | **Express.js**     | Minimalist framework for building RESTful APIs.                                                                                                            |\n|                | **Multer**         | Middleware for handling file uploads (multipart/form-data).                                                                                                |\n| **AI**         | **Google Gemini**  | API for multimodal (text and image) content generation.                                                                                                    |\n| **Language**   | **TypeScript**     | Used end-to-end for strict typing and better developer experience.                                                                                         |\n| **Deployment** | **Docker \u0026 Nginx** | Containerization for consistent and isolated deployments. Nginx serves the production Angular app as a high-performance web server.                        |\n\n---\n\n## ⚡ Getting Started\n\nFollow these steps to set up and run the project locally.\n\n### Prerequisites\n\nMake sure you have the following installed:\n\n- **Node.js** (v22 or higher) and **npm**\n- **Angular CLI** (`npm install -g @angular/cli`)\n- **Docker** and **Docker Compose** (optional)\n\n---\n\n### Installation and Configuration\n\nClone the repository:\n\n```bash\ngit clone https://github.com/damiansire/GenAI-Scaffold.git\ncd GenAI-Scaffold\n```\n\nCreate your environment file by copying the example:\n\n```bash\ncp env.example .env\n```\n\nEdit `.env` and add your Google Gemini API key:\n\n```\nGEMINI_API_KEY=YOUR_API_KEY_HERE\n```\n\n**Get your Gemini API key here:** https://aistudio.google.com/app/apikey\n\n\u003e **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.\n\nInstall dependencies (npm Workspaces will handle both frontend and backend):\n\n```bash\nnpm install\n```\n\n### Running the Application\n\n#### Option 1: Development Mode (Recommended for development)\n\n```bash\nnpm run dev\n```\n\n- **Angular frontend**: http://localhost:4200\n- **Node.js backend**: http://localhost:3000\n\n#### Option 2: Docker Mode (Recommended for production/testing)\n\n```bash\n# Start Docker Desktop first (macOS)\nopen -a Docker\n\n# Build and run with Docker\ndocker compose up --build -d\n\n# Check service status\ndocker compose ps\n\n# View logs\ndocker compose logs -f\n```\n\n- **Angular frontend**: http://localhost:8080\n- **Node.js backend**: http://localhost:3000\n\n**Health Checks:**\n\n```bash\ncurl http://localhost:3000/health  # API\ncurl http://localhost:8080/health  # Frontend\n```\n\n\u003e **Troubleshooting Docker:** Refer to `REGISTRY.md` for current deployment architectures and known edge cases.\n\n---\n\n## 🌟 AI Features\n\nThis platform includes three powerful AI capabilities powered by Google's models:\n\n### 📝 Multi-Tiered Generation \u0026 Generative UI\n\n- Routing across the **Google** model plugins that ship today (`google-text-bison`, `gemini-image-gen`, `google-vision-ocr`). *Multi-provider routing to other frontier models (e.g. Claude 3.5 Sonnet, Gemini 1.5 Pro) and local SLMs is on the roadmap — there is currently no Anthropic/OpenAI integration in the codebase.*\n- **Server-Driven Generative UI**: Angular dynamically renders visual components via `@defer` based on LLM Tool Calls.\n- **Iterative Refinement (RCI)**: Recursive generation and quality scoring in worker threads.\n- Token usage tracking and real-time streaming via SSE.\n\n### 🔍 Image OCR (Google Vision OCR)\n\n- Extract text from images with high accuracy\n- Multi-language support (10+ languages)\n- Bounding box detection for text positioning\n- Confidence scores for each annotation\n- Supports JPEG, PNG, GIF, WEBP, BMP formats\n\n### 🎨 Image Generation - Nano Banana (Gemini 2.5 Flash Image)\n\n**NEW!** Generate and edit images using Gemini's native image generation:\n\n**Modes:**\n\n- **Text-to-Image**: Create images from descriptive prompts\n- **Image Editing**: Modify existing images with text instructions\n- **Style Transfer**: Apply artistic styles to photos\n- **Multi-Image Composition**: Combine elements from multiple images\n- **Iterative Refinement**: Conversational image editing\n\n**Capabilities:**\n\n- 10 aspect ratios (Square, Portrait, Landscape, Widescreen, etc.)\n- High-fidelity text rendering in images (logos, diagrams, posters)\n- Photorealistic rendering with advanced lighting and camera controls\n- Illustration and sticker generation\n- Product mockups and commercial photography\n- Sequential art (comic panels, storyboards)\n\n**Prompting Best Practices:**\n\n- Describe scenes narratively, not just keywords\n- Use photography terms for realism (lens type, lighting, camera angle)\n- Be hyper-specific about details\n- Iterate conversationally for refinement\n- Use step-by-step instructions for complex scenes\n\n**Note:** All generated images include a SynthID watermark.\n\n---\n\n## 🏢 Enterprise AI Platform Capabilities\n\nBeyond being a simple starter template, GenAI-Scaffold is architected as a **B2B SaaS-ready AI Platform**. It includes built-in enterprise features that address the most critical business requirements:\n\n### 🧠 Integrated RAG Infrastructure (Retrieval-Augmented Generation)\n- **Chat with Private Data**: Seamlessly ingest and query private documents and customer databases without the prohibitive cost of fine-tuning models.\n- **Native Vector DB (optional, off by default)**: *Designed* to use the `sqlite-vec` extension for in-memory semantic search. `sqlite-vec` is **not a bundled dependency**: it must be provided as an external SQLite extension at runtime. If it is not loadable, the database logs `Semantic vector search disabled` and only the exact-match (SHA-256) cache path operates.\n- **Dynamic Context Injection**: Automatically enriches LLM prompts with relevant semantic context to reduce hallucinations.\n\n### 🛡️ Guardrails \u0026 AI Safety Firewall\n- **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.)*\n- **PII Masking**: Automatic detection and masking of Personally Identifiable Information (emails, credit cards) *before* data leaves your infrastructure to reach public APIs.\n- **Toxicity Filters**: Guarantees brand safety by actively blocking inappropriate or non-compliant generations.\n\n### 📊 Comprehensive LLMOps \u0026 Observability\n- **ROI \u0026 Billing Visibility**: Granular tracking of Token Consumption and Latency (TTFT) per user and per tenant, essential for B2B billing models.\n- **Distributed Tracing**: Uses Node.js `AsyncLocalStorage` and native OTLP telemetry to trace every interaction from the HTTP request down to the SQLite vector cache and the LLM API call.\n- **Low-Cost Caching**: The **exact-match** cache (SHA-256 of the prompt) serves identical repeat queries with ~0ms latency and 0 token cost. The **semantic** (paraphrase-tolerant) path requires the optional `sqlite-vec` extension and is off by default; without it, paraphrased queries are not cache hits.\n\n### 🏢 Multi-Tenant Architecture (design, not yet implemented)\n\u003e ⚠️ **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_id`** yet. Do **not** rely on this for compliance — the items below describe the intended design.\n- **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.\n- **Tier-Based RBAC (partial)**: `rbac` middleware 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.\n\n---\n\n## 🗂️ Project Structure\n\nOptimized for scalability and clarity:\n\n```\n/GenAI-Scaffold/\n├── packages/               # Monorepo packages\n│   ├── client/            # Angular 21 Application\n│   │   ├── src/app/\n│   │   │   ├── core/       # Singleton services, DI tokens\n│   │   │   ├── shared/     # Reusable components (file-upload, navigation)\n│   │   │   └── features/   # Functional components (text-model, image-model)\n│   │   └── package.json\n│   └── api/               # Node.js API\n│       ├── src/\n│       │   ├── api/        # Routes, controllers, middleware\n│       │   ├── core/       # Base classes (ApiError)\n│       │   ├── models/     # Factory, Registry, Loader\n│       │   └── plugins/    # AI model strategies\n│       └── package.json\n├── .docker/               # Dockerfiles for production\n│   ├── Dockerfile.client  # Angular + Nginx\n│   ├── Dockerfile.server  # Node.js API\n│   └── nginx.conf         # Nginx configuration\n├── REGISTRY.md            # Master Architectural Registry (Decisions \u0026 Patterns)\n├── package.json           # Workspace configuration\n├── package-lock.json      # Dependency lock file\n├── env.example            # Environment variables template (copy to .env)\n└── docker-compose.yml     # Container orchestration\n```\n\n---\n\n## ✅ Best Practices Implemented\n\n### Backend (Node.js)\n\n- **Secure API Key Handling**: All secrets are managed via environment variables — never hardcoded.\n- **File Uploads**: `multer` configured per route to efficiently and securely handle multipart/form-data.\n- **Strict CORS Policy**: Only trusted origins are allowed in production.\n\n### Frontend (Angular 21)\n\n- **100% Standalone Components**: No NgModules — less boilerplate, simpler dependency management.\n- **Signal Forms**: Uses Angular 21's `form()` / `FormField` API from `@angular/forms/signals` for type-safe, model-driven forms.\n- **Reactive State with Signals**: Uses `signal()`, `computed()`, and `httpResource()` for high-performance state management.\n- **Zoneless Change Detection**: Runs without `zone.js` via `provideZonelessChangeDetection()` for smaller bundles and better performance.\n- **OnPush Change Detection**: All components use `ChangeDetectionStrategy.OnPush`.\n- **Vitest Test Runner**: Unit tests run with Vitest via `@angular/build:unit-test` for fast, modern testing.\n- **Design Tokens**: Centralized CSS custom properties in `:root` for consistent theming across components.\n- **Accessibility (ARIA)**: Decorative emojis wrapped in `aria-hidden`, form inputs with `aria-invalid` / `aria-describedby`, spinners with `role=\"status\"`.\n- **Lazy Loading with `loadComponent`**: Reduces initial bundle size and improves performance.\n- **Modern Dependency Injection**: Uses `inject()` with `InjectionToken` for API configuration.\n- **Native Control Flow**: Leverages `@if`, `@for`, and `@switch` syntax for cleaner, faster templates.\n\n---\n\n## 📚 Documentation\n\nAll comprehensive documentation, architecture decisions, and setup instructions have been consolidated into a single source of truth:\n\n- **[Master Architectural Registry (REGISTRY.md)](./REGISTRY.md)** - Contains API references, setup workflow, component structures, and Node.js native patterns.\n\n## 🐳 Production Deployment with Docker\n\nThe project is fully containerized and ready for production deployment.\n\n- **Multi-stage Builds**: Each Dockerfile separates build and runtime environments for smaller, secure images.\n- **Workspace Support**: Dockerfiles are configured for npm workspaces (monorepo architecture)\n- **Nginx for Frontend**: The built Angular app is served via an optimized Nginx container for SPA delivery.\n- **Health Checks**: Both services include health check endpoints for monitoring\n- **Single Command Orchestration**: The `docker-compose.yml` file spins up the full production stack easily.\n\nTo build and run production containers:\n\n```bash\n# Start Docker Desktop first (macOS)\nopen -a Docker\n\n# Build and run all services\ndocker compose build\ndocker compose up -d\n\n# Check status (both services should be healthy)\ndocker compose ps\n\n# View logs\ndocker compose logs -f\n\n# Stop services\ndocker compose down\n```\n\n**Useful Commands:**\n\n```bash\n# Rebuild without cache\ndocker compose build --no-cache\n\n# Build specific service\ndocker compose build api\ndocker compose build client\n\n# View service logs\ndocker compose logs -f api\ndocker compose logs -f client\n\n# Execute commands in running container\ndocker compose exec api sh\ndocker compose exec client sh\n```\n\n**Architecture Notes:**\n\n- The API service uses a multi-stage build with TypeScript compilation\n- Dependencies are installed using `npm ci --workspace` for monorepo support\n- Production TypeScript configuration relaxes strictness for deployment\n- Nginx serves the Angular app with SPA routing support and compression\n\nFor detailed orchestration and operational guidelines, refer to the `REGISTRY.md`.\n\n---\n\n## 🤝 Contributing\n\nContributions, suggestions, and improvements are welcome!  \nFeel free to open a pull request or issue if you'd like to help enhance this blueprint.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamiansire%2Fgenai-fullstack-blueprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdamiansire%2Fgenai-fullstack-blueprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdamiansire%2Fgenai-fullstack-blueprint/lists"}