# for-hives/forvoyez architecture

> Architecture diagram of the GitHub repository for-hives/forvoyez, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/for-hives/forvoyez
- Repository: https://github.com/for-hives/forvoyez

## Overview

##### Main Components
- Frontend Client: Built in Next.js with pages/components for landing, sign-in, sign-up, dashboard (including billing, legal, tokens, usage, and interactive playground for API testing). This component deals with user interaction and presents the SEO metadata and other visual elements.
- API Layer: Next.js API endpoints ([/api/describe], [/api/hello], [/api/tokens], [/api/sync], [/api/webhook]) that orchestrate business logic. They receive image data, trigger processing, and return metadata.
- Service Layer: The src/services folder contains multiple services (e.g., imageDescription.service.js, jwt.service.js, lemonsqueezy.service.js, prisma.service.js, webhook.service.js) that encapsulate business logic such as image analysis, token management, payment events, and database interactions.
- Database: A PostgreSQL database (with migrations generated by Prisma using the prisma/schema.prisma and migration SQL files) is used as the persistence layer.
- External Integrations:
- OpenAI: The service that powers the image metadata generation with advanced AI.
- Lemonsqueezy: For subscription and webhook events (with dedicated webhook configuration instructions and API endpoints).
- Webhook Forwarding Tools: Tools like Webhook.site and ngrok are used for testing and local development when handling Lemonsqueezy webhooks.
- Auxiliary Components:
- Testing Suites: The project integrates both end-to-end (e2e with Playwright) and unit tests (using Vitest) to ensure reliability.
- DevOps/CI: GitHub workflows, Dockerfile, and environment/configuration files (e.g., .env.example, Dockerfile) support deployment and continuous integration.
- Build/Styling: Tailwind CSS (for styling) and configurations for eslint, prettier, and husky file hooks maintain code quality.

##### Relationships and Data Flow
- Client–Server Interaction: The user’s browser interacts with the Next.js frontend. When, for example, an image is uploaded on the landing or dashboard page, the frontend sends a POST request to the /api/describe endpoint.
- API Processing Layer: The API endpoint forwards the image and any context to the imageDescription service. In parallel, token validation might occur via the jwt.service to ensure secure access.
- Business Logic Execution: Once the image is received, the service layer handles preprocessing, calls out to external AI engines (like OpenAI) to generate SEO-friendly metadata, and wraps the output in a JSON schema.
- Database Interaction: Service calls (using Prisma via prisma.service) record user data, API usage statistics, tokens, etc., in the PostgreSQL database.
- External Communication: For actions like subscription management, data is synchronized with Lemonsqueezy and processed in webhooks routed through /api/webhook.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly differentiate between the presentation layer (frontend), API endpoints, service/business logic layer, and data access (Prisma/Database).
- Modular Structure: Leverage the clear folder separation (src/app, src/api, src/services, src/components) to illustrate modularity.
- API Gateway Pattern: Next.js API routes act as a gateway for client requests, consolidating business logic and routing internal service calls.
- Security: Highlight token management (JWT) and secure API access, as described in the README.
- Extensibility: Emphasize the ease with which new features (e.g., additional integrations or new metadata customization options) can be added thanks to the plugin-like architecture in components and clear directory structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F("Frontend Client"):::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API("API Endpoints (/api/*)"):::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        SD("ImageDescription Service"):::backend
        JWT("JWT Service"):::backend
        Lemo("Lemonsqueezy Service"):::backend
        PrismaS("Prisma Service"):::backend
        Webhook("Webhook Service"):::backend
    end

    %% Database
    subgraph "Database & Persistence"
        DB("PostgreSQL Database"):::backend
    end

    %% External Integrations
    subgraph "External Integrations"
        OA("OpenAI"):::external
        LemoConf("Lemonsqueezy Config"):::external
    end

    %% Testing Suites
    subgraph "Testing Suites"
        TEST("Automated Tests (Unit & E2E)"):::ci
    end

    %% DevOps & Build
    subgraph "DevOps & Build"
        GH("GitHub Workflows"):::ci
        DOCKER("Dockerfile"):::ci
        TAILWIND("Tailwind Config"):::ci
        STYLES("Styles"):::ci
    end

    %% Main Data Flow
    F -->|"APIRequest"| API
    API -->|"ProcessRequest"| SD
    API -->|"ValidateToken"| JWT

    SD -->|"CallAI"| OA
    JWT -->|"ForwardForPersistence"| PrismaS
    PrismaS -->|"PersistData"| DB
    Lemo -->|"HandleSubscription"| LemoConf
    Webhook -->|"ProcessWebhook"| LemoConf

    SD -->|"ReturnMetadata"| API
    JWT -->|"ReturnValidation"| API
    PrismaS -->|"PersistAck"| API
    Lemo -->|"SubscriptionUpdate"| API
    Webhook -->|"WebhookAck"| API
    API -->|"SendResponse"| F

    %% Testing and DevOps integration
    TEST -->|"CITrigger"| GH
    GH -->|"DeployAPI"| API
    GH -->|"DeployServices"| SD
    DOCKER -->|"DeployLocalDB"| DB
    TAILWIND -->|"ApplyStyles"| F

    %% Styling of Nodes
    classDef frontend fill:#ADD8E6,stroke:#007ACC,stroke-width:2px;
    classDef backend fill:#C1E1C1,stroke:#228B22,stroke-width:2px;
    classDef external fill:#FFD580,stroke:#FFA500,stroke-width:2px;
    classDef ci fill:#E0BBE4,stroke:#DA70D6,stroke-width:2px;

    %% Click Events for Component Mapping
    click F "https://github.com/for-hives/forvoyez/tree/main/src/app"
    click API "https://github.com/for-hives/forvoyez/tree/main/src/app/api"
    click SD "https://github.com/for-hives/forvoyez/blob/main/src/services/imageDescription.service.js"
    click JWT "https://github.com/for-hives/forvoyez/blob/main/src/services/jwt.service.js"
    click Lemo "https://github.com/for-hives/forvoyez/blob/main/src/services/lemonsqueezy.service.js"
    click PrismaS "https://github.com/for-hives/forvoyez/blob/main/src/services/prisma.service.js"
    click Webhook "https://github.com/for-hives/forvoyez/blob/main/src/services/webhook.service.js"
    click DB "https://github.com/for-hives/forvoyez/tree/main/prisma"
    click LemoConf "https://github.com/for-hives/forvoyez/tree/main/bruno"
    click TEST "https://github.com/for-hives/forvoyez/tree/main/tests"
    click GH "https://github.com/for-hives/forvoyez/tree/main/.github/workflows"
    click DOCKER "https://github.com/for-hives/forvoyez/tree/main/Dockerfile"
    click TAILWIND "https://github.com/for-hives/forvoyez/blob/main/tailwind.config.js"
    click STYLES "https://github.com/for-hives/forvoyez/tree/main/src/styles"
```
