# crystallizeapi/furniture-remix architecture

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

- Interactive diagram: https://gitdiagram.com/crystallizeapi/furniture-remix
- Repository: https://github.com/crystallizeapi/furniture-remix

## Overview

##### Project Type and Purpose
- This is a full-stack web application built using Remix Run as a framework.
- It is intended to serve as a boilerplate for Crystallize-powered stores. The application handles storefront operations, order management, payment integrations (with providers like Adyen, Stripe, Vipps, etc.), and supports multilingual and multi-tenant features.
- The README also indicates support for a local development workflow with Docker, local HTTPS via a Caddy proxy, and integrations like Mailcatcher and Redis.

##### File Structure
- The top-level “application” folder contains all the core parts of the Remix Run app:
- Source code in the “src” directory is organized into sub-folders for “ui” (React components, pages, and state management), “core” (server-specific logic like authentication and cookies), “routes” (defining both page routes and API endpoints), and “use-cases” (business logic, payment handling, data fetchers, mappers, etc.).
- The “provisioning” directory includes infrastructure-related files such as Docker Compose configurations and files for reverse-proxy (Caddy) and local development (e.g., tenant and clone setups).
- The “.github” folder holds continuous integration workflows and templates that ensure development quality.
- The presence of numerous directories under “use-cases” (e.g., payments, crystallize read/write, contracts, mapper, etc.) shows that there is a strong emphasis on separating domain logic and integration code for external services.

##### Key Architectural Components
a. Frontend (Client-side UI):
- Represented by React components, pages, and UI libraries located under “application/src/ui” and "application/src/routes".
- Components such as product listings, shopping cart, checkout forms, and payment components.

b. Backend (Server-side / API Endpoints):
- Represented by the Remix routes in “application/src/routes” that handle web requests both for user-facing pages and API calls (order placement, payment processing, magicklink authentication, etc.).
- Server logic in “application/src/core” for cookies, authentication, and server-rendering aspects.

c. Business Logic & Use-Cases:
- The “application/src/use-cases” directory encapsulates core business logic such as checkout handling, payments processing with different providers (Adyen, Stripe, Vipps, etc.), data mapping, and service API integrations.

d. External and Infrastructure Services:
- Docker-managed services such as Mailcatcher (for email testing), Redis (for caching or session storage), and the Caddy proxy that provides HTTPS termination.
- You may also highlight integration with third-party payment gateways and Crystallize’s API endpoints for content and storefront data.

e. Development & Deployment Tools:
- Use of provisioning files (docker-compose.yaml, Caddyfile) that aid in local development and deployment.
- Mention the Makefile commands (e.g., “make serve” and “make stop”) that help orchestrate these services.

##### Architectural Patterns & Principles
- The system is designed following a layered architecture: separation of concerns between presentation (UI), business logic (use-cases), and system integration (external APIs and infrastructure).
- There is a clear separation between frontend and backend, with remix routes handling server-side logic and React components providing dynamic client-side interactions.
- Modularity is further highlighted through the “use-cases” and “mapper” folders, enforcing SRP (Single Responsibility Principle) and reusability across the code.

##### Final Suggestions
- Be as detailed as possible—don’t shy away from separating out the use-case components and API endpoints if they represent distinct functionality.
- Elements unique to this project, like the integration with Crystallize, the provisioning for local development using Docker, and how the Remix framework organizes routes and business logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Frontend Layer
    subgraph "Client/Frontend Layer"
        F1["React UI Components"]:::frontend
        F2["Route Definitions (UI Pages)"]:::frontend
    end

    %% Server/Backend Layer
    subgraph "Server/Backend Layer"
        B1["Auth & Cookies"]:::backend
        B2["Root Rendering"]:::backend
        B3["Remix API Endpoints"]:::backend
    end

    %% Business Logic & Use-Cases
    subgraph "Business Logic & Use-Cases"
        U1["Payment Handling"]:::business
        U2["Checkout Process"]:::business
        U3["Cart Update"]:::business
        U4["Crystallize Data Fetching"]:::business
        U5["Data Mapper"]:::business
    end

    %% Infrastructure & External Services
    subgraph "Infrastructure & External Services"
        I1["Dev Infrastructure (Docker, Caddy, Mailcatcher, Redis)"]:::infra
        I2["Tenant Setups"]:::infra
        I3["Payment Gateways/Crystallize API"]:::infra
    end

    %% Development & Deployment Tools
    subgraph "Development & Deployment Tools"
        D1["Makefile Commands"]:::dev
        D2["CI/CD Workflows & Templates"]:::dev
    end

    %% Connections from Frontend to Backend
    F1 -->|"UserInteractions"| B3
    F2 -->|"PageRequests"| B2

    %% Connections within Backend
    B3 -->|"triggers"| U1
    B3 -->|"triggers"| U2
    B3 -->|"triggers"| U3
    B3 -->|"triggers"| U4
    B3 -->|"triggers"| U5
    B1 -->|"storesSessionIn"| I1
    B2 -->|"usesDevInfra"| I1
    B3 -->|"supportsMultiTenant"| I2

    %% Connections from Business Use-Cases to External Services
    U1 -->|"integrates"| I3
    U4 -->|"fetchesDataFrom"| I3
    U5 -->|"mapsDataFrom"| I3

    %% Connections from Development Tools to Infrastructure
    D1 -->|"orchestrates"| I1
    D2 -->|"deploysTo"| I1

    %% Class definitions with colors
    classDef frontend fill:#FDEEF4,stroke:#C7254E,stroke-width:2px;
    classDef backend fill:#E8F4FD,stroke:#31708F,stroke-width:2px;
    classDef business fill:#FFF9E6,stroke:#8A6D3B,stroke-width:2px;
    classDef infra fill:#E6F4EA,stroke:#3C763D,stroke-width:2px;
    classDef dev fill:#FEF3E2,stroke:#8A6D3B,stroke-width:2px;

    %% Click Events
    click F1 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/ui"
    click F2 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/routes"
    click B1 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/core"
    click B2 "https://github.com/crystallizeapi/furniture-remix/blob/main/application/src/root.tsx"
    click B3 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/routes"
    click U1 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/use-cases/payments"
    click U2 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/use-cases/checkout"
    click U3 "https://github.com/crystallizeapi/furniture-remix/blob/main/application/src/use-cases/updateCart.server.ts"
    click U4 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/use-cases/crystallize"
    click U5 "https://github.com/crystallizeapi/furniture-remix/tree/main/application/src/use-cases/mapper"
    click I1 "https://github.com/crystallizeapi/furniture-remix/tree/main/provisioning/dev"
    click I2 "https://github.com/crystallizeapi/furniture-remix/tree/main/provisioning/tenant"
    click D1 "https://github.com/crystallizeapi/furniture-remix/tree/main/Makefile"
    click D2 "https://github.com/crystallizeapi/furniture-remix/blob/main/.github"
```
