# leanlag87/catfecito-pern architecture

> Architecture diagram of the GitHub repository leanlag87/catfecito-pern, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leanlag87/catfecito-pern
- Repository: https://github.com/leanlag87/catfecito-pern

## Overview

#### Purpose and entry points
CatFecito is a serverless ecommerce system: a React/Vite client consumes an AWS API Gateway-backed Lambda API for catalog, accounts, carts, orders, administration, and payments. Client bootstraps at `client/src/main.jsx`, composes global UI/auth providers in `client/src/app/providers/AppProviders.jsx`, and selects pages/guards through `client/src/app/routes/AppRoutes.jsx`. Backend deployment and HTTP/resource topology begin at `serverless.yml`.

#### Client application shell and access control
The SPA owns navigation, protected routes, modal state, and inactivity behavior. Authentication state and role checks are feature-local, while route guards constrain user/admin screens before their data flows execute.
- `client/src/features/auth/stores/authStore.js`
- `client/src/features/auth/hooks/useRequireRole.js`
- `client/src/app/routes/routeGuards.jsx`

#### Client domain feature boundary
Each major ecommerce domain follows a UI → hooks → service → client-side store pattern. Product browsing/filtering, cart mutation, checkout/order tracking, profiles, and administration are independent feature modules, limiting cross-domain UI coupling.
- `client/src/features/products/services/products.service.js`
- `client/src/features/cart/stores/cartStore.js`
- `client/src/features/orders/hooks/useOrderCheckout.js`

#### API integration flow
Feature services call a shared HTTP abstraction, configured with API endpoints and environment-derived connectivity. API responses update feature stores and render components; authenticated calls carry the client’s auth context/token. This is the boundary between browser state and the serverless backend.
- `client/src/config/apiClient.js`
- `client/src/config/apiEndpoints.js`
- `client/src/services/api.js`

#### Lambda API and layered business logic
API Gateway invokes discrete Node.js Lambda handlers. Handlers delegate to services for business rules, then repositories for DynamoDB access, preserving a clear controller/service/data boundary. The Serverless configuration splits endpoint registrations by domain and defines provider concerns such as HTTP API, IAM, CORS, DynamoDB, and S3.
- `server/functions/users/orders/createOrder.js`
- `server/services/order.service.js`
- `server/repositories/order.repository.js`

#### Identity, authorization, and administration
Registration/login integrate JWT and AWS Cognito helpers; an authorizer protects authenticated API routes. Admin handlers/services separately govern product, category, user, and order management, enforcing the privileged control-plane boundary.
- `server/functions/auth/authorizer.js`
- `server/services/auth.service.js`
- `server/services/admin/order.service.js`

#### Commerce transaction and payment lifecycle
A customer cart is persisted through cart handlers/services/repository; order creation turns checkout intent into an order, then payment preference creation delegates to MercadoPago. MercadoPago calls the webhook, which queries/updates payment state and the associated order. DynamoDB atomic transactions are the core consistency mechanism; payment handling is an external asynchronous boundary.
- `server/functions/users/cart/addToCart.js`
- `server/functions/payments/createPreference.js`
- `server/functions/payments/webhook.js`

#### Runtime, infrastructure, and delivery
The backend runs Node.js 20.x on AWS Lambda behind API Gateway, uses DynamoDB for application data, S3 for product images, Cognito for identity, MercadoPago for payment processing, and CloudWatch logging. The React app is containerized and served by Nginx; environment-specific Docker Compose and GitHub Actions pipelines support dev, staging, and production delivery.
- `docker/client/Dockerfile`
- `docker/client/nginx.conf`
- `.github/workflows/cd-prod.yml`

Main entry points: [`client/src/features/products/services/products.service.js`](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/products/services/products.service.js) (Commerce features), [`serverless.yml`](https://github.com/leanlag87/catfecito-pern/blob/main/serverless.yml) (Serverless topology), [`server/services/order.service.js`](https://github.com/leanlag87/catfecito-pern/blob/main/server/services/order.service.js) (Business services), [`client/src/app/routes/AppRoutes.jsx`](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/routes/AppRoutes.jsx) (Routes and pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_bootstrap["Client bootstrap<br/>React entry<br/>[main.jsx]"]
  node_app_providers["Global providers<br/>app shell<br/>[AppProviders.jsx]"]
  node_app_routes["Routes and pages<br/>routing<br/>[AppRoutes.jsx]"]
  node_route_guards["Route guards<br/>access control<br/>[routeGuards.jsx]"]
  node_auth_store["Auth state<br/>feature store<br/>[authStore.js]"]
  node_role_hook["Role checks<br/>auth hook<br/>[useRequireRole.js]"]
  node_commerce_features["Commerce features<br/>UI/hooks/services/stores"]
  node_cart_store["Cart state<br/>feature store<br/>[cartStore.js]"]
  node_checkout_hook["Checkout flow<br/>order hook"]
  node_api_client["API client<br/>HTTP boundary<br/>[apiClient.js]"]
end

subgraph group_backend["Serverless API"]
  node_serverless_config["Serverless topology<br/>deployment config<br/>[serverless.yml]"]
  node_lambda_handlers["Lambda handlers<br/>HTTP handlers<br/>[createOrder.js]"]
  node_business_services["Business services<br/>service layer<br/>[order.service.js]"]
  node_repositories["Repositories<br/>data access"]
  node_authorizer_auth["Auth and authorizer<br/>identity boundary<br/>[authorizer.js]"]
  node_admin_services["Admin control plane<br/>admin service<br/>[order.service.js]"]
  node_cart_handler["Cart persistence<br/>cart handler<br/>[addToCart.js]"]
  node_payment_preference["Payment preference<br/>payment handler"]
  node_payment_webhook["Payment webhook<br/>payment handler<br/>[webhook.js]"]
end

subgraph group_aws["AWS runtime"]
  node_dynamodb[("DynamoDB<br/>application data")]
  node_s3[("S3 product images<br/>object storage")]
  node_cognito["Amazon Cognito<br/>identity provider"]
end

subgraph group_external["External services"]
  node_mercadopago{{"MercadoPago<br/>payment gateway"}}
end

subgraph group_delivery["Delivery"]
  node_nginx_client["Nginx client image<br/>container runtime"]
  node_prod_cd["Production CD<br/>GitHub Actions<br/>[cd-prod.yml]"]
end

node_client_bootstrap -->|"mounts"| node_app_providers
node_app_providers -->|"provides context to"| node_app_routes
node_app_routes -->|"enforces"| node_route_guards
node_route_guards -->|"reads session"| node_auth_store
node_route_guards -->|"checks roles with"| node_role_hook
node_app_routes -->|"renders"| node_commerce_features
node_commerce_features -->|"updates"| node_cart_store
node_commerce_features -->|"uses"| node_checkout_hook
node_commerce_features -->|"calls"| node_api_client
node_api_client -->|"HTTP API"| node_serverless_config
node_serverless_config -->|"registers routes"| node_lambda_handlers
node_serverless_config -->|"attaches authorizer"| node_authorizer_auth
node_lambda_handlers -->|"delegates to"| node_business_services
node_business_services -->|"persists through"| node_repositories
node_repositories -->|"reads and writes"| node_dynamodb
node_serverless_config -->|"provisions access"| node_s3
node_authorizer_auth -->|"integrates with"| node_cognito
node_lambda_handlers -->|"admin operations"| node_admin_services
node_cart_handler -->|"cart rules"| node_business_services
node_checkout_hook -->|"starts payment"| node_payment_preference
node_payment_preference -->|"creates preference"| node_mercadopago
node_mercadopago -.->|"payment event"| node_payment_webhook
node_payment_webhook -->|"updates order state"| node_business_services
node_prod_cd -->|"builds and deploys"| node_nginx_client

click node_client_bootstrap "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/main.jsx"
click node_app_providers "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/providers/AppProviders.jsx"
click node_app_routes "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/routes/AppRoutes.jsx"
click node_route_guards "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/routes/routeGuards.jsx"
click node_auth_store "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/auth/stores/authStore.js"
click node_role_hook "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/auth/hooks/useRequireRole.js"
click node_commerce_features "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/products/services/products.service.js"
click node_cart_store "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/cart/stores/cartStore.js"
click node_checkout_hook "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/orders/hooks/useOrderCheckout.js"
click node_api_client "https://github.com/leanlag87/catfecito-pern/blob/main/client/src/config/apiClient.js"
click node_serverless_config "https://github.com/leanlag87/catfecito-pern/blob/main/serverless.yml"
click node_lambda_handlers "https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/users/orders/createOrder.js"
click node_business_services "https://github.com/leanlag87/catfecito-pern/blob/main/server/services/order.service.js"
click node_repositories "https://github.com/leanlag87/catfecito-pern/blob/main/server/repositories/order.repository.js"
click node_authorizer_auth "https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/auth/authorizer.js"
click node_admin_services "https://github.com/leanlag87/catfecito-pern/blob/main/server/services/admin/order.service.js"
click node_cart_handler "https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/users/cart/addToCart.js"
click node_payment_preference "https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/payments/createPreference.js"
click node_payment_webhook "https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/payments/webhook.js"
click node_nginx_client "https://github.com/leanlag87/catfecito-pern/blob/main/docker/client/Dockerfile"
click node_prod_cd "https://github.com/leanlag87/catfecito-pern/blob/main/.github/workflows/cd-prod.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_bootstrap,node_app_providers,node_app_routes,node_route_guards,node_auth_store,node_role_hook,node_commerce_features,node_cart_store,node_checkout_hook,node_api_client toneBlue
class node_serverless_config,node_lambda_handlers,node_business_services,node_repositories,node_authorizer_auth,node_admin_services,node_cart_handler,node_payment_preference,node_payment_webhook toneAmber
class node_dynamodb,node_s3,node_cognito toneMint
class node_mercadopago toneRose
class node_nginx_client,node_prod_cd toneIndigo
```

## Components

### React client

- [Client bootstrap](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/main.jsx): React entry · `client/src/main.jsx`
- [Global providers](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/providers/AppProviders.jsx): app shell · Composes UI and authentication context. · `client/src/app/providers/AppProviders.jsx`
- [Routes and pages](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/routes/AppRoutes.jsx): routing · `client/src/app/routes/AppRoutes.jsx`
- [Route guards](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/app/routes/routeGuards.jsx): access control · `client/src/app/routes/routeGuards.jsx`
- [Auth state](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/auth/stores/authStore.js): feature store · `client/src/features/auth/stores/authStore.js`
- [Role checks](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/auth/hooks/useRequireRole.js): auth hook · `client/src/features/auth/hooks/useRequireRole.js`
- [Commerce features](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/products/services/products.service.js): UI/hooks/services/stores · Products, cart, checkout, profiles, and admin remain feature-local. · `client/src/features/products/services/products.service.js`
- [Cart state](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/cart/stores/cartStore.js): feature store · `client/src/features/cart/stores/cartStore.js`
- [Checkout flow](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/features/orders/hooks/useOrderCheckout.js): order hook · `client/src/features/orders/hooks/useOrderCheckout.js`
- [API client](https://github.com/leanlag87/catfecito-pern/blob/main/client/src/config/apiClient.js): HTTP boundary · Adds endpoint configuration and authenticated request context. · `client/src/config/apiClient.js`

### Serverless API

- [Serverless topology](https://github.com/leanlag87/catfecito-pern/blob/main/serverless.yml): deployment config · Defines HTTP API, IAM, CORS, DynamoDB, and S3 resources. · `serverless.yml`
- [Lambda handlers](https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/users/orders/createOrder.js): HTTP handlers · Domain-specific handlers receive API Gateway requests. · `server/functions/users/orders/createOrder.js`
- [Business services](https://github.com/leanlag87/catfecito-pern/blob/main/server/services/order.service.js): service layer · Applies commerce rules and transaction orchestration. · `server/services/order.service.js`
- [Repositories](https://github.com/leanlag87/catfecito-pern/blob/main/server/repositories/order.repository.js): data access · `server/repositories/order.repository.js`
- [Auth and authorizer](https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/auth/authorizer.js): identity boundary · JWT/Cognito authentication protects API routes. · `server/functions/auth/authorizer.js`
- [Admin control plane](https://github.com/leanlag87/catfecito-pern/blob/main/server/services/admin/order.service.js): admin service · Governs privileged product, category, user, and order actions. · `server/services/admin/order.service.js`
- [Cart persistence](https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/users/cart/addToCart.js): cart handler · `server/functions/users/cart/addToCart.js`
- [Payment preference](https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/payments/createPreference.js): payment handler · Creates MercadoPago checkout preferences. · `server/functions/payments/createPreference.js`
- [Payment webhook](https://github.com/leanlag87/catfecito-pern/blob/main/server/functions/payments/webhook.js): payment handler · Reconciles asynchronous payment status with orders. · `server/functions/payments/webhook.js`

### AWS runtime

- **DynamoDB**: application data · Atomic transactions provide order and payment consistency.
- **S3 product images**: object storage
- **Amazon Cognito**: identity provider

### External services

- **MercadoPago**: payment gateway · External asynchronous payment boundary.

### Delivery

- [Nginx client image](https://github.com/leanlag87/catfecito-pern/blob/main/docker/client/Dockerfile): container runtime · Serves the built React application. · `docker/client/Dockerfile`
- [Production CD](https://github.com/leanlag87/catfecito-pern/blob/main/.github/workflows/cd-prod.yml): GitHub Actions · `.github/workflows/cd-prod.yml`

## Connections

- Client bootstrap → Global providers: mounts
- Global providers → Routes and pages: provides context to
- Routes and pages → Route guards: enforces
- Route guards → Auth state: reads session
- Route guards → Role checks: checks roles with
- Routes and pages → Commerce features: renders
- Commerce features → Cart state: updates
- Commerce features → Checkout flow: uses
- Commerce features → API client: calls
- API client → Serverless topology: HTTP API
- Serverless topology → Lambda handlers: registers routes
- Serverless topology → Auth and authorizer: attaches authorizer
- Lambda handlers → Business services: delegates to
- Business services → Repositories: persists through
- Repositories → DynamoDB: reads and writes
- Serverless topology → S3 product images: provisions access
- Auth and authorizer → Amazon Cognito: integrates with
- Lambda handlers → Admin control plane: admin operations
- Cart persistence → Business services: cart rules
- Checkout flow → Payment preference: starts payment
- Payment preference → MercadoPago: creates preference
- MercadoPago → Payment webhook: payment event
- Payment webhook → Business services: updates order state
- Production CD → Nginx client image: builds and deploys