# Stack Architecture & Technical Specifications — Gruperly

Este documento define la arquitectura, convenciones y especificaciones del stack tecnológico para el desarrollo del monorepo de **Gruperly**. Debe ser utilizado como contexto principal por los agentes e instruccionales de IA para la generación de código y configuración del proyecto.

---

## 1. Stack Tecnológico Principal

### Runtime & Monorepo Manager
* **Runtime:** Bun (1.4)
* **Package Manager:** Bun (bun install / bun --filter)
* **Monorepo Tooling:** bun workspaces + Turborepo

### Backend (`apps/backend`)
* **Framework:** [Hono](https://hono.dev/) (servido con `Bun.serve`, ejecutado con `bun --watch`)
* **ORM:** [Prisma](https://www.prisma.io/)
* **Base de Datos:** PostgreSQL
* **Autenticación:** [Better Auth](https://www.better-auth.com/)
* **Validación de Entradas:** `validator` de hono (`hono/validator`) + `Zod.safeParse`

### Frontend (`apps/web`)
* **Framework / Library:** React 19+ con TypeScript
* **Routing:** [TanStack Router](https://tanstack.com/router) (File-based routing)
* **Data Fetching & State:** [TanStack Query](https://tanstack.com/query) (v5)
* **UI Components:** [Shadcn UI](https://ui.shadcn.com/)
* **Styling:** Tailwind CSS (v4)
* **Form Management:** `react-hook-form` con `@hookform/resolvers/zod`

### Shared Package (`packages/shared`)
* **Validación de Esquemas:** [Zod](https://zod.dev/)
* **Tipos Compartidos:** Tipos inferidos de Zod (`z.infer<typeof schema>`) y tipos globales exportados de Prisma.

---

## 2. Estructura del Monorepo

```text
gruperly/
├── apps/
│   ├── backend/                  # Servicio Backend (Bun + Hono)
│   │   ├── src/
│   │   │   ├── http/             # Infraestructura HTTP (validate, problem-details, session-auth, ...)
│   │   │   ├── lib/              # Prisma (cliente + UnitOfWork), pagination, email, helpers
│   │   │   ├── modules/          # Módulos: health-check, auth, groups, attendees, payments, waitlist
│   │   │   │   └── <módulo>/
│   │   │   │       ├── routes.ts
│   │   │   │       └── features/<accion>/{route,use-case}.ts
│   │   │   ├── app.ts            # Monta basePath('/api/v1') + rutas + notFound/onError (RFC 7807)
│   │   │   ├── server.ts         # Entry point (Bun.serve)
│   │   │   └── logger.ts         # pino + pino-pretty
│   │   ├── prisma/
│   │   │   ├── schema.prisma     # Generator + datasource simple
│   │   │   ├── models/           # Modelos multi-archivo (auth.prisma, domain.prisma)
│   │   │   └── migrations/
│   │   ├── generated/            # Cliente generado de Prisma (gitignoreado, alias @generated/*)
│   │   ├── prisma.config.ts      # Config de Prisma CLI (datasource URL, migrations)
│   │   ├── test/                 # Tests bun test
│   │   ├── tsconfig.json
│   │   └── package.json
│   │
│   └── web/                     # Aplicación Frontend (React PWA)
│       ├── src/
│       │   ├── components/      # Componentes de Shadcn UI y UI propia
│       │   ├── routes/          # Rutas jerárquicas de TanStack Router
│       │   ├── lib/             # Cliente de API, TanStack Query client, etc.
│       │   ├── main.tsx
│       │   └── index.css        # Tailwind CSS
│       ├── tsconfig.json
│       └── package.json
│
├── packages/
│   ├── shared/                  # Código y esquemas compartidos
│   │   ├── src/
│   │   │   ├── schemas/         # Validaciones Zod compartidas
│   │   │   │   ├── group.schema.ts
│   │   │   │   ├── attendee.schema.ts
│   │   │   │   └── payment.schema.ts
│   │   │   └── index.ts
│   │   ├── tsconfig.json
│   │   └── package.json
│   │
│   └── config/                  # Configuraciones compartidas de TS/ESLint
│       ├── tsconfig.base.json
│       └── package.json
│
├── package.json                 # Workspaces de Bun
├── turbo.json                   # Configuración de pipeline de Turborepo
└── README.md

---

## 3. Sistema de Diseño Visual (UI System Tokens)

* **Background:** `#F8FAFC` (Light Mode principal)
* **Primary Color (Nav, Headings, Textos oscuros):** `#0A2540` (Azul Marino del Isologo)
* **Accent Color (Botones de acción, enlaces activos, CTAs):** `#1E90FF` (Azul Celeste de la 'y')
* **Border Radius:** `0.75rem` (`rounded-xl` en tarjetas de Shadcn)
* **Status Badges:**
  * **Paid / Al Día:** Fondo `#DCFCE7`, Texto `#10B981`
  * **Pending / Lista Espera:** Fondo `#FEF3C7`, Texto `#F59E0B`