# fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio architecture

> Architecture diagram of the GitHub repository fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio
- Repository: https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Browser
    Browser["User Browser"]:::external

    %% Frontend Layer
    subgraph "Next.js Frontend"
        direction TB
        AppDir["src/app"]:::frontend
        Page["page.tsx"]:::frontend
        Layout["layout.tsx"]:::frontend
        Globals["globals.css"]:::frontend

        subgraph "UI Components"
            direction TB
            UIkit["UI Component Library"]:::frontend
        end

        subgraph "AI Client Logic"
            direction TB
            Dev["dev.ts"]:::frontend
            Genkit["genkit.ts"]:::frontend
            FlowClient["generate-excuse.ts"]:::frontend
        end

        subgraph "Hooks & Utilities"
            direction TB
            Hooks1["use-mobile.tsx"]:::frontend
            Hooks2["use-toast.ts"]:::frontend
            Utils["utils.ts"]:::frontend
        end

        subgraph "Next.js Configs"
            direction TB
            Config1["next.config.ts"]:::config
            Config2["tailwind.config.ts"]:::config
            Config3["tsconfig.json"]:::config
        end

        subgraph "Documentation"
            direction TB
            Docs1["blueprint.md"]:::config
            Docs2["components.json"]:::config
        end
    end

    %% Backend Orchestration Layer
    subgraph "n8n Workflow" 
        direction TB
        Webhook["Webhook Node"]:::backend
        AIcall["AI Service Node"]:::backend
        Transform["Transformation/Logging Node"]:::backend
        ResponseNode["Webhook Response Node"]:::backend
    end

    %% External AI Service
    ExtAI["External AI Service"]:::external

    %% Hosting
    Firebase["Firebase Hosting"]:::external

    %% Data Flow
    Browser -->|Uses UI| Page
    Page -->|Uses client logic| FlowClient
    FlowClient -->|POST /webhook| Webhook
    Webhook -->|invoke Gemini API call| AIcall
    AIcall -->|API request| ExtAI
    ExtAI -->|API response| AIcall
    AIcall -->|pass result| Transform
    Transform -->|format response| ResponseNode
    ResponseNode -->|HTTP response| FlowClient
    FlowClient -->|update UI| Page

    Firebase -->|hosts| Browser

    %% Click Events
    click AppDir "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/tree/main/src/app"
    click Page "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/app/page.tsx"
    click Layout "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/app/layout.tsx"
    click Globals "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/app/globals.css"
    click UIkit "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/tree/main/src/components/ui"
    click Dev "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/ai/dev.ts"
    click Genkit "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/ai/genkit.ts"
    click FlowClient "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/ai/flows/generate-excuse.ts"
    click Config1 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/next.config.ts"
    click Config2 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/tailwind.config.ts"
    click Config3 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/tsconfig.json"
    click Docs1 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/docs/blueprint.md"
    click Docs2 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/components.json"
    click Hooks1 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/hooks/use-mobile.tsx"
    click Hooks2 "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/hooks/use-toast.ts"
    click Utils "https://github.com/fedy-benhassouna/excusely-with-n8n-and-firebase-ai-studio/blob/main/src/lib/utils.ts"

    %% Styles
    classDef frontend fill:#D6E4FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D3F9D8,stroke:#333,stroke-width:1px
    classDef external fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px
```
