100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
# 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` |