How luis-m23/shipglobal works
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