# alan24rs/balet architecture

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

- Interactive diagram: https://gitdiagram.com/alan24rs/balet
- Repository: https://github.com/alan24rs/balet

## Overview

##### Project Type and Purpose
- Valet is a full-stack web application built with Next.js 15 (App Router) and React + TypeScript.
- It provides a public front end for drivers (map search, geolocation) and an admin panel for parking-lot owners, backed by Supabase (PostgreSQL + RLS + functions) and serverless API routes.

##### Top-Level Components
- Frontend Client (React/Next.js pages & components)
- Next.js Server (App Router handlers, API routes, middleware)
- Supabase Database (tables, views, RLS policies, triggers, stored functions)
- Business Logic Layer (src/services + RPC calls)
- External Services:
- Google Maps / Places API
- Resend Email API
- Deployment & CI/CD: Vercel + GitHub Actions (migrations in build)

##### Relationships and Data Flows
- Browser ←→ Next.js Client Components (React UI, Context Providers, Hooks)
- Client Components → Supabase Browser Client (direct queries + subscriptions for live data)
- Next.js API Routes & Server Components → Supabase Admin Client (secure server calls, migrations, Cron endpoints)
- Next.js Middleware → guards admin routes via Supabase Auth & Role checks
- Cron Routes (e.g., `/api/cron/generar-boletas`) scheduled via external scheduler trigger or manual call
- Notification Flow: services → Resend API for email invitations
- Geo Flow: client → Google Places API for autocomplete & map rendering

##### Architectural Patterns
- App Router + Server/Client Components separation
- Service Layer pattern (`src/services/*`) abstracting all DB and external-API calls
- Hook-based data fetching & mutations (`src/hooks/queries`, `src/hooks/mutations`)
- Context Providers for cross-cutting concerns (Theme, Query, Geolocation)
- Zod schemas (`src/schemas`) for validating inputs both client and server
- RLS + Stored Procedures in Supabase for data security and business rules

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        PublicUI["Public Driver UI<br/>(Next.js Pages & React)"]:::client
        AdminUI["Admin Panel UI<br/>(Next.js Pages & React)"]:::client
    end

    subgraph "Server Layer"
        AppRouter["App Router<br/>(src/app)"]:::server
        APIRoutes["API Routes<br/>(src/app/api)"]:::server
        Middleware["Middleware<br/>(src/middleware.ts)"]:::server
        ServiceLayer["Service Layer<br/>(src/services)"]:::server
        Cron["Cron Endpoint<br/>(src/app/api/cron/generar-boletas/route.ts)"]:::server
        AuthAPI["Authentication Routes<br/>(src/app/api/auth & src/app/auth)"]:::server
    end

    subgraph "Database Layer"
        DB["Supabase DB<br/>(Postgres + RLS + Functions)"]:::db
    end

    subgraph "External Services"
        GoogleMaps["Google Maps API"]:::external
        ResendEmail["Resend Email API"]:::external
    end

    subgraph "CI/CD Pipeline"
        GHActions["GitHub Actions"]:::ci
        Vercel["Vercel"]:::ci
        Scripts["Migration Scripts<br/>(scripts/)"]:::ci
    end

    %% Flows
    PublicUI -->|"HTTP SSR/SSG"| AppRouter
    PublicUI -->|"Supabase Browser Client"| DB
    AdminUI -->|"HTTP SSR/SSG"| AppRouter
    AdminUI -->|"Supabase Browser Client"| DB

    AppRouter -->|"routes & server components"| APIRoutes
    AppRouter -->|"auth & role guards"| Middleware
    APIRoutes -->|"Admin Supabase Client"| DB
    AuthAPI -->|"Auth RPC & callbacks"| DB
    Cron -->|"Scheduled RPC calls"| DB

    ServiceLayer -->|"RPC & Queries"| DB
    ServiceLayer -->|"Uses"| GoogleMaps
    ServiceLayer -->|"Uses"| ResendEmail

    GHActions -->|"trigger deploy"| Vercel
    Vercel -->|"run migrations"| Scripts
    Scripts -->|"apply migrations"| DB

    %% Click Events
    click PublicUI "https://github.com/alan24rs/balet/tree/main/src/app"
    click PublicUI "https://github.com/alan24rs/balet/tree/main/src/components"
    click PublicUI "https://github.com/alan24rs/balet/tree/main/src/components/ui"
    click AppRouter "https://github.com/alan24rs/balet/tree/main/src/app"
    click APIRoutes "https://github.com/alan24rs/balet/tree/main/src/app/api"
    click Middleware "https://github.com/alan24rs/balet/blob/main/src/middleware.ts"
    click Middleware "https://github.com/alan24rs/balet/blob/main/src/lib/supabase/middleware.ts"
    click DB "https://github.com/alan24rs/balet/tree/main/supabase/migrations"
    click DB "https://github.com/alan24rs/balet/blob/main/supabase/config.toml"
    click DB "https://github.com/alan24rs/balet/blob/main/supabase/schema_reference.sql"
    click ServiceLayer "https://github.com/alan24rs/balet/tree/main/src/services"
    click ServiceLayer "https://github.com/alan24rs/balet/blob/main/src/lib/supabase/admin.ts"
    click ServiceLayer "https://github.com/alan24rs/balet/blob/main/src/lib/supabase/browser.ts"
    click ServiceLayer "https://github.com/alan24rs/balet/blob/main/src/lib/supabase/server.ts"
    click GoogleMaps "https://github.com/alan24rs/balet/blob/main/src/services/google/index.ts"
    click ResendEmail "https://github.com/alan24rs/balet/blob/main/src/services/email/sendInvitationEmail.ts"
    click Cron "https://github.com/alan24rs/balet/blob/main/src/app/api/cron/generar-boletas/route.ts"
    click AuthAPI "https://github.com/alan24rs/balet/blob/main/src/app/api/auth/callback/route.ts"
    click AuthAPI "https://github.com/alan24rs/balet/blob/main/src/app/auth/actions.ts"
    click GHActions "https://github.com/alan24rs/balet/blob/main/.github/workflows/deploy.yml"
    click GHActions "https://github.com/alan24rs/balet/blob/main/.github/workflows/preview-deploy.yml"
    click Vercel "https://github.com/alan24rs/balet/blob/main/vercel.json"
    click Scripts "https://github.com/alan24rs/balet/blob/main/scripts/conditional-migrate.sh"
    click Scripts "https://github.com/alan24rs/balet/blob/main/scripts/check-migrations.sh"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef server fill:#DFFFE0,stroke:#28a745,color:#155724;
    classDef db fill:#FFF4D0,stroke:#e8a317,color:#8a6d3b;
    classDef external fill:#F3D0FF,stroke:#6f42c1,color:#4e2960;
    classDef ci fill:#E2E3E5,stroke:#6c757d,color:#343a40;
```
