# belastrittmatter/framely architecture

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

- Interactive diagram: https://gitdiagram.com/belastrittmatter/framely
- Repository: https://github.com/belastrittmatter/framely

## Overview

##### Main Components
- Client (Browser): Represents users interacting with the application via web browsers.
- Next.js Web Server: The heart of the application that serves pages, components, and API routes. This will include:
- The Dynamic Routing System (evidenced by directories like src/app/[domain] and src/app/[domain]/[slug]) handling multi-tenancy and custom domains.
- Rendering Layers: Differentiating between server-side components (pages, API endpoints) and client-side components (interactive dashboard and editor).
- Authentication Service: External integration with Clerk to manage user sessions and authentication.
- Dashboard Module: Found in src/app/dashboard and related components in src/app/components/dashboard, this module handles site management (create, view, and manage sites).
- Website Builder Editor: The drag-and-drop interface built from components found throughout src/app/components/editor and subdirectories (editor sidebar, editor navigation, various editor components for text, images, containers, etc.).
- Backend and API Layer: Includes business logic and actions (see src/lib/actions) for processing page data, site structure, and user interactions.
- Database Layer: Represented by the prisma directory (with schema.prisma) and auxiliary database access scripts in src/lib/db.ts. This layer communicates with a MySQL database using Prisma ORM.
- UI Component Library: Located in src/components/ui, showing that shared UI components (accordion, button, dialog, etc.) are used across different pages and modules.
- External Analytics & Other Services: Integration with Umami Analytics for site analytics and possibly other external services as noted in the README.

##### Relationships and Data Flow
- A client initiates requests through a browser that hit the Next.js server.
- The Next.js server uses its dynamic routing to render pages, with specific routes for dashboards, editors, and publicly accessible website pages.
- User authentication is managed via Clerk, which interfaces with both the client and server.
- The dashboard and editor components interact with back-end API routes (triggered by client events or page navigation) to interact with the database through Prisma.
- Data flows from UI interactions in the website builder to the backend logic that manipulates and persists website content.
- External analytics (Umami) can be represented as a service that collects usage data across the site.

##### Architectural Patterns & Key Design Principles
- MVC/MVVM-like Separation: Although Next.js encourages file-based routing with server components, the separation between pages (views), business logic (API/actions), and data models (Prisma) is evident.
- Modular Component Design: The extensive use of UI components and modularized editor/dashboard features follows a component-driven design which makes the system maintainable and scalable.
- Multi-Tenancy & Dynamic Routing: Folder structures with dynamic segments ([domain], [slug], [siteId]) indicate an architectural choice to support multi-tenant behavior and dynamic content delivery.
- Emphasis on Extensibility: With plans for additional features (e.g., dynamic OG cards, SEO optimizations), the system shows a design that can easily incorporate new modules or external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Client (Browser)"):::client
    Client -->|"Accesses"| NextJs("Next.js Web Server"):::server

    subgraph "Next.js Web Server"
        NextContent("Page Rendering & API Serving"):::server
        NextContent -.-> Dynamic1("Dynamic Routing [domain]"):::server
        NextContent -.-> Dynamic2("Dynamic Routing [slug]"):::server
        NextContent -->|"Renders"| Dashboard("Dashboard Module"):::module
        NextContent -->|"Renders"| Editor("Website Builder Editor"):::module
        NextContent -->|"Processes"| Backend("Backend & API Layer"):::api
    end

    NextJs -->|"AuthChecks"| Clerk("Authentication (Clerk)"):::external
    Dashboard -->|"Uses"| UI("UI Component Library"):::ui
    Editor -->|"Uses"| UI
    Backend -->|"DBQueries"| Database("Database Layer"):::db
    NextJs -->|"SendsAnalytics"| Umami("External Analytics (Umami)"):::external

    %% Click Events
    click NextJs "https://github.com/belastrittmatter/framely/tree/main/src/app"
    click Dynamic1 "https://github.com/belastrittmatter/framely/tree/main/src/app/[domain]"
    click Dynamic2 "https://github.com/belastrittmatter/framely/tree/main/src/app/[domain]/[slug]"
    click Dashboard "https://github.com/belastrittmatter/framely/tree/main/src/app/dashboard"
    click Dashboard "https://github.com/belastrittmatter/framely/tree/main/src/app/components/dashboard"
    click Editor "https://github.com/belastrittmatter/framely/tree/main/src/app/editor"
    click Editor "https://github.com/belastrittmatter/framely/tree/main/src/app/components/editor"
    click Editor "https://github.com/belastrittmatter/framely/tree/main/src/app/providers"
    click Backend "https://github.com/belastrittmatter/framely/blob/main/src/lib/actions/page.ts"
    click Backend "https://github.com/belastrittmatter/framely/tree/main/src/lib/actions"
    click Database "https://github.com/belastrittmatter/framely/blob/main/prisma/schema.prisma"
    click Database "https://github.com/belastrittmatter/framely/blob/main/src/lib/db.ts"
    click UI "https://github.com/belastrittmatter/framely/tree/main/src/components/ui"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#cfc,stroke:#333,stroke-width:2px;
    classDef api fill:#fcf,stroke:#333,stroke-width:2px;
    classDef db fill:#ff9,stroke:#333,stroke-width:2px;
    classDef ui fill:#9ff,stroke:#333,stroke-width:2px;
    classDef external fill:#faa,stroke:#333,stroke-width:2px;
```
