# juanmunozmedina/maquiavelowines architecture

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

- Interactive diagram: https://gitdiagram.com/juanmunozmedina/maquiavelowines
- Repository: https://github.com/juanmunozmedina/maquiavelowines

## Overview

##### Main Components
- Frontend (Client-side):
– The static site/rendered pages (located under “src/pages”) representing various routes (home, product pages, collection pages, legal pages, etc.).
– UI Components (in “src/components” and “src/components/ui”) which include reusable elements like buttons, drawers, and layout components that give the site its appearance.
– Features: Domain-specific modules (in “src/features”) such as the product, collection, and cart modules that encapsulate business logic and state management.
- Backend / Server Side:
– Actions (in “src/actions”) that serve as endpoints to update cart state or other backend functionality.
– API endpoints (inside “src/pages/api”), particularly for handling payment processing through Stripe.
- External Services:
– Payment Service (Stripe): Used in the API endpoints to manage payments.
– Email Service (Loops): For sending customer confirmation and internal fulfillment emails.
– Geolocation/Map Service (Google Maps): For embedding maps related to order/shipping details.
– Custom/store API: Either via the live API as described or the simulated API implementation in “src/lib/client.mock.ts”.
- Configuration and Tooling:
– Environment management (with astro:env etc.) via configuration files (astro.config.ts, tsconfig.json, tailwind.config.ts, etc.) to integrate with the required external services and manage client/server privileges.
– Testing & Linting Tools: Directories like “e2e” and configurations like “playwright.config.ts”, “vitest.config.ts”, etc., that help ensure reliability.
– Deployment configuration: Files like “netlify.toml” and CI workflows captured in the “workflows” directory.

##### Relationships and Interactions
- Data Flow for Page Rendering and Interactivity:
– The “pages” route incoming HTTP requests to specific Astro pages that incorporate both static rendering and dynamic content (via the islands architecture).
– UI Components (from the “components” directories) and Feature Modules (from “src/features”) are responsible for displaying content and capturing user interaction.
– Frontend actions (located in “src/actions”) process client events (e.g., add-to-cart actions) which call backend functions to update server-side state.
- Communication with External APIs:
– Payment flows involve routes under “pages/api/checkout” that integrate with Stripe.
– Email notifications and map embedding occur when orders are processed, involving calls to Loops and Google Maps respectively.
- Integration Points:
– A clear separation exists between client-rendered views and server-rendered functions (utilizing Astro actions and dynamic endpoints), ensuring improved performance and security.

##### Architectural Patterns & Design Principles
- Island Architecture: For on-demand interactivity with minimal runtime cost, where Astro renders static HTML with small interactive islands (powered by SolidJS).
- Separation of Concerns: Different directories for UI components, domain features (cart, product, collection), and API endpoints.
- Modular Integration: Use of separate modules (e.g., “src/lib/client” vs “src/lib/client.mock”) to facilitate swapping out of APIs and services.
- Clear Dependency Injection via configuration (e.g., environment variables for external service keys).

- Rectangles for main modules (frontend, backend).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Group
    subgraph "Frontend"
        F1["Pages (Static & Islands)"]:::frontend
        subgraph "Components"
            F2["Core Components"]:::frontend
            F3["UI Components"]:::frontend
        end
        F4["Domain Features"]:::frontend
        F4a["Cart Feature"]:::frontend
    end

    %% Backend Group
    subgraph "Backend Services"
        B1["Actions (Cart Management)"]:::backend
        subgraph "API Endpoints"
            B2["Checkout API (Payment)"]:::backend
            B2b["Checkout Success"]:::backend
        end
    end

    %% External Services Group
    subgraph "External Services"
        C1["Stripe (Payment)"]:::external
        C2["Loops.so (Emails)"]:::external
        C3["Google Maps (Geolocation)"]:::external
        C4["Custom Store API (Simulated)"]:::external
    end

    %% Configuration and Tooling Group
    subgraph "Configuration & Tooling"
        D1["Server Config & Env"]:::config
        subgraph "Config Files"
            D1a["astro.config.ts"]:::config
            D1b["tsconfig.json"]:::config
            D1c["tailwind.config.ts"]:::config
            D1d["src/env.d.ts"]:::config
        end
        D2["Testing & Deployment"]:::config
        subgraph "Test/CI Tools"
            D2a["e2e (cart.spec.ts)"]:::config
            D2b["playwright.config.ts"]:::config
            D2c["vitest.config.ts"]:::config
            D2d["netlify.toml"]:::config
            D2e["Workflows"]:::config
        end
    end

    %% Connections - Frontend to Backend
    F1 -->|"triggers"| B1
    F1 -->|"fetchesData"| B2
    F2 ---|"rendersWithin"| F1
    F3 ---|"rendersWithin"| F1
    F4a -->|"updatesState"| B1
    F4 -->|"encapsulates"| F4a

    %% Backend internal connections
    B1 -->|"callsAPI"| B2

    %% Connections from Backend to External Services
    B2 -->|"processesPayment"| C1
    B2 -->|"sendsEmail"| C2
    B2 -->|"embedsMap"| C3
    B2 -->|"fetchesStoreData"| C4

    %% Configuration influence (dashed lines)
    D1 -.-> F1
    D1 -.-> F2
    D1 -.-> F3
    D1 -.-> F4
    D1 -.-> B1
    D1 -.-> B2

    %% Styles
    classDef frontend fill:#e6f2ff,stroke:#000,stroke-width:1px;
    classDef backend fill:#ffe6cc,stroke:#000,stroke-width:1px;
    classDef external fill:#d5e8d4,stroke:#000,stroke-width:1px;
    classDef config fill:#f9f7e8,stroke:#000,stroke-width:1px;

    %% Click Events
    click F1 "https://github.com/juanmunozmedina/maquiavelowines/tree/main/src/pages"
    click F2 "https://github.com/juanmunozmedina/maquiavelowines/tree/main/src/components"
    click F3 "https://github.com/juanmunozmedina/maquiavelowines/tree/main/src/components/ui"
    click F4 "https://github.com/juanmunozmedina/maquiavelowines/tree/main/src/features"
    click F4a "https://github.com/juanmunozmedina/maquiavelowines/tree/main/src/features/cart"
    click B1 "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/actions/cart.ts"
    click B2 "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/pages/api/checkout.ts"
    click B2b "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/pages/api/checkout/success.ts"
    click C2 "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/lib/emails.ts"
    click C4 "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/lib/client.mock.ts"
    click D1a "https://github.com/juanmunozmedina/maquiavelowines/blob/main/astro.config.ts"
    click D1b "https://github.com/juanmunozmedina/maquiavelowines/blob/main/tsconfig.json"
    click D1c "https://github.com/juanmunozmedina/maquiavelowines/blob/main/tailwind.config.ts"
    click D1d "https://github.com/juanmunozmedina/maquiavelowines/blob/main/src/env.d.ts"
    click D2a "https://github.com/juanmunozmedina/maquiavelowines/blob/main/e2e/cart.spec.ts"
    click D2b "https://github.com/juanmunozmedina/maquiavelowines/blob/main/playwright.config.ts"
    click D2c "https://github.com/juanmunozmedina/maquiavelowines/blob/main/vitest.config.ts"
    click D2d "https://github.com/juanmunozmedina/maquiavelowines/blob/main/netlify.toml"
    click D2e "https://github.com/juanmunozmedina/maquiavelowines/tree/main/workflows"
```
