How juanmunozmedina/maquiavelowines works
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).