# luis-m23/shipglobal architecture

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

- Interactive diagram: https://gitdiagram.com/luis-m23/shipglobal
- Repository: https://github.com/luis-m23/shipglobal

## Overview

##### Project type and purpose
- ShipGlobal is a full-stack, international parcel management web app built with Next.js (app router) and backed by Supabase (Auth, database, realtime).

##### File structure
- **app/** – Next.js App Router pages and layouts. Contains routes for public pages (login, register, home), authenticated user pages (dashboard, perfil, tracking, calculadora, factura), and **/admin/** routes for CRUD pages.
- **components/** – UI primitives (under ui/), shared layout & modal components, theme providers, toasts.
- **hooks/** – custom React hooks (useMobile, useToast).
- **lib/** –
· **supabase/** – client and admin SDK config plus service-level wrappers (authService, paqueteService, etc.)
· **middleware/** – session validation.
· **validation/** – Zod schemas for form data.
· **utils.ts**, **navigation.ts**, **enum.ts**, **map.ts** – shared helpers.
- **public/** – static assets (audio).
- Config files: next.config.mjs, postcss.config, tsconfig.json, package.json.

##### README for additional insights
- Uses pnpm, environment variables for Supabase URL, keys.

a. Main components:
- Client (Browser / Mobile web)
- Next.js frontend (Server-Side Rendering, API routes via lib/supabase/client)
- Supabase backend (Postgres database, Auth service, Realtime, Storage if used)
- External services (optional SMS/Email for notifications if implemented)
b. Relationships and interactions:
1. User ↔ Next.js pages via HTTP(S)
2. Next.js ↔ Supabase Auth for login, session tokens
3. Next.js ↔ Supabase database via client/admin SDK calls in service layer
4. Supabase Realtime → Next.js (or directly to client) for live notifications/tracking updates
c. Architectural patterns:
- Layered architecture: Presentation (app/pages, components) → Service/API layer (lib/supabase/services) → Data layer (Supabase)
- Middleware for auth guard (validateSession)
- Domain-driven modules: each business concept (paquetes, categorias, promociones) has its own service and validation schema
- Reusable UI component library under components/ui
d. Key technologies/frameworks:
- Next.js App Router (page.tsx, layout.tsx)
- React + TypeScript
- Supabase (JS client, Auth, Postgres, Realtime)
- Zod (validation in lib/validation)
- PNPM build tooling

##### Detailed architectural capture
- Routing layer (app/layout.tsx + page.tsx files)
- Component library (components/ui, components/*)
- Service layer (lib/supabase/services/*)
- Validation layer (lib/validation/*)
- Middleware (lib/middleware/validateSession.ts)
- Auth Service
- Postgres DB (tables: usuarios, paquetes, facturas, etc.)
- Realtime (can push tracking updates, notifications)
- Flow of a sample use-case:
1. User logs in → call authService → Supabase Auth → returns JWT → stored in Next.js session
2. User requests package list → Next.js service layer calls paqueteService → queries Supabase DB → returns data → Next.js renders page
3. New notification arrives → Supabase Realtime pushes to client (via browser or Next.js proxy) → UI component (app-notification) displays toast

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Presentation Layer"
    direction TB
    Browser["Browser (Client)"]:::frontend
    NextApp["Next.js Frontend"]:::frontend
    Browser -->|"HTTP(S) Requests"| NextApp
  end

  subgraph "Next.js Internal"
    direction TB
    Routing["Routing Layer"]:::frontend
    UI["UI Components"]:::frontend
    Hooks["Custom Hooks"]:::frontend
    Middleware["Auth Middleware"]:::frontend
    ClientConfig["Supabase Client Config"]:::frontend
    Services["Service Layer"]:::frontend
    Validation["Validation Layer"]:::frontend

    Routing --> UI
    UI --> Hooks
    UI --> Middleware
    Hooks --> ClientConfig
    ClientConfig --> Services
    Services --> Validation
  end

  NextApp --> Routing

  subgraph "Backend (Supabase)"
    direction TB
    AuthService["Supabase Auth"]:::backend
    Database["Postgres Database"]:::backend
    Realtime["Realtime Service"]:::backend
  end

  NextApp -->|"Auth calls"| AuthService
  NextApp -->|"CRUD Calls"| Database
  Realtime -->|"Push Updates"| NextApp
  Database --> Realtime

  click Routing "https://github.com/luis-m23/shipglobal/blob/main/app/layout.tsx"
  click Routing "https://github.com/luis-m23/shipglobal/blob/main/app/page.tsx"
  click Routing "https://github.com/luis-m23/shipglobal/blob/main/app/login/page.tsx"
  click Routing "https://github.com/luis-m23/shipglobal/blob/main/app/dashboard/page.tsx"
  click Routing "https://github.com/luis-m23/shipglobal/blob/main/app/admin/.../page.tsx"
  click UI "https://github.com/luis-m23/shipglobal/tree/main/components/ui/*"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/dashboard-layout.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/app-notification.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/app-loader.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/theme-provider.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/theme-toggle.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/themed-toast-container.tsx"
  click UI "https://github.com/luis-m23/shipglobal/blob/main/components/auth-provider.tsx"
  click Hooks "https://github.com/luis-m23/shipglobal/blob/main/hooks/use-mobile.ts"
  click Hooks "https://github.com/luis-m23/shipglobal/blob/main/hooks/use-toast.ts"
  click Middleware "https://github.com/luis-m23/shipglobal/blob/main/lib/middleware/validateSession.ts"
  click Middleware "https://github.com/luis-m23/shipglobal/blob/main/middleware.ts"
  click ClientConfig "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/client.ts"
  click ClientConfig "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/admin.ts"
  click ClientConfig "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/errorMap.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/authService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/registroService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/usuarioService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/usuarioMetadataService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/paqueteService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/paqueteDetalleService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/casilleroService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/categoriaService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/direccionService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/distritoService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/factorConversionService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/calculadoraService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/facturaService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/promocionService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/recompensaService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/notificacionService.ts"
  click Services "https://github.com/luis-m23/shipglobal/blob/main/lib/supabase/services/realtimeService.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/login.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/registro.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/usuario.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/usuarioMetadata.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/paquete.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/casillero.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/categoria.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/direccion.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/distrito.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/factorConversion.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/calculadora.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/promociones.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/recompensa.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/notificacion.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/cotizacion.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/estadoEnvio.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/password.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/pais.ts"
  click Validation "https://github.com/luis-m23/shipglobal/blob/main/lib/validation/tipoServicio.ts"
  click Database "https://github.com/luis-m23/shipglobal/blob/main/public/sounds/beepy.mp3"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/next.config.mjs"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/tsconfig.json"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/postcss.config.mjs"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/package.json"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/pnpm-lock.yaml"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/components.json"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/app/globals.css"
  click NextApp "https://github.com/luis-m23/shipglobal/blob/main/styles/globals.css"

  classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
  classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
