How fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio works
Project Type and Purpose
• Excusely is a full-stack web application whose front end is authored in Next.js (TypeScript + Tailwind CSS + Firebase AI Studio) and whose backend logic lives in n8n workflows, triggered by webhooks.
• Purpose: Accept user input (situation/context), forward it to AI services via n8n, then return a humorous excuse to the UI.
File Structure
• Top-level files: next.config.ts, tailwind.config.ts, tsconfig.json → Next.js configuration.
• src/app, src/components → Next.js 13 “app router” front end.
• src/ai/dev.ts, src/ai/flows/*.ts, src/ai/genkit.ts → custom client-side hooks/utilities that call n8n webhook endpoints and/or wrap AI kit.
• docs/blueprint.md and components.json hint at internal API definitions and documentation.
• No direct database folder: back end persistence and orchestration live in n8n, not in the repo.
Extract Architecture Insights from README
• Front end: built in Firebase AI Studio (here realized as a customized Next.js app using Firebase AI Studio under the hood).
• Back end: orchestrated via n8n, which hosts a workflow (excuse-generator.json) that invokes the AI model (e.g., Gemini API) and returns results via HTTP.
• Communication: Webhook from Next.js → n8n → external AI service → n8n → HTTP response → Next.js.
Main Components & Their Interactions
a. Frontend Application (Next.js + Tailwind + Firebase AI Studio)
– UI pages/components (src/app/page.tsx, src/components/ui/*).
– Client-side code (src/ai/dev.ts, genkit.ts) that collects user input and posts it to the backend webhook.
b. n8n Workflow Engine
– A hosted n8n instance importing excuse-generator.json.
– Defines a webhook node that listens for POST requests.
– AI service node (Gemini, OpenAI, etc.) invoked with user payload.
– Any transformation or logging nodes.
– Webhook response node that sends the generated excuse back.
c. External AI Service (e.g., Gemini / OpenAI)
– Receives prompt from n8n; returns generated text.
d. Hosting/Infrastructure
– Firebase (serving the Next.js app via Firebase AI Studio hosting or Firebase Hosting).
– n8n server (could be self-hosted, Docker, or n8n cloud).
Architectural Patterns & Design Principles
• Separation of concerns: UI vs. orchestration vs. AI.
• Event-driven / webhook-driven integration: loosely coupled via HTTP.
• Reusable UI component library (src/components/ui).
• Environment-agnostic AI flows: n8n can swap AI providers without touching UI.