docs: agregar README.md con detalles técnicos y setup

2026-05-28 14:40:48 -03:00
parent 7bc3d9f898
commit 3bacaa9fa8
1 changed files with 118 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,118 @@
+# Personal Admin 2026
+
+Dashboard personal para seguimiento de cotizaciones (USD/BNA, USD/Blue, USDC/ARS-Belo) con actualizaciones en tiempo real.
+
+## Stack
+
+| Capa | Tecnología |
+|------|-----------|
+| **Runtime** | [Bun](https://bun.sh) |
+| **Backend** | [Hono](https://hono.dev/) + TypeScript |
+| **Frontend** | [React 19](https://react.dev/) + [Vite](https://vitejs.dev/) |
+| **Routing** | [TanStack Router](https://tanstack.com/router) (file-based) |
+| **Data Fetching** | [TanStack Query](https://tanstack.com/query) |
+| **Estilos** | [Tailwind CSS v4](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/) |
+| **Base de datos** | PostgreSQL + [Prisma ORM](https://www.prisma.io/) |
+| **Tiempo real** | Server-Sent Events (SSE) |
+| **Contenedor** | Docker (multi-stage build) |
+
+## Estructura
+
+```
+├── apps/
+│   ├── backend/       # API server (Hono) + cron jobs
+│   │   └── src/modules/quotes/   # Módulo de cotizaciones
+│   │       ├── bna.service.ts    # USD oficial (dolarito.ar)
+│   │       ├── blue.service.ts   # USD blue (dolarito.ar)
+│   │       └── belo.service.ts   # USDC/ARS Belo (criptoya.com)
+│   └── frontend/      # SPA React con TanStack Router
+│       └── src/
+│           ├── routes/           # Páginas (file-based routing)
+│           ├── features/         # Componentes de cada feature
+│           ├── components/ui/    # shadcn/ui components
+│           └── lib/              # Hooks, API client, utils
+├── packages/
+│   └── common/        # Tipos y utilidades compartidas
+└── Dockerfile         # Multi-stage build
+```
+
+## Requisitos
+
+- [Bun](https://bun.sh) >= 1.x
+- PostgreSQL (local o remota)
+
+## Setup local
+
+```bash
+# Instalar dependencias
+bun install
+
+# Configurar base de datos
+cp apps/backend/.env apps/backend/.env.local
+# Editar DATABASE_URL en .env.local
+
+# Generar Prisma client
+bun run --cwd apps/backend prisma:generate
+
+# Correr migraciones
+bun run --cwd apps/backend prisma:migrate
+
+# Iniciar dev (backend + frontend simultáneamente)
+bun run dev
+```
+
+El backend corre en `http://localhost:3000` y el frontend en `http://localhost:5173` (con proxy a `/api` → `:3000`).
+
+## Scripts
+
+### Root
+| Comando | Descripción |
+|---------|-------------|
+| `bun run dev` | Inicia backend y frontend en paralelo |
+| `bun run build` | Build de frontend |
+
+### Backend (`apps/backend`)
+| Comando | Descripción |
+|---------|-------------|
+| `bun run dev` | Dev con watch |
+| `bun run prisma:generate` | Generar Prisma client |
+| `bun run prisma:migrate` | Migraciones de desarrollo |
+| `bun run prisma:migrate:deploy` | Migraciones en producción |
+| `bun run prisma:studio` | Prisma Studio (GUI DB) |
+
+### Frontend (`apps/frontend`)
+| Comando | Descripción |
+|---------|-------------|
+| `bun run dev` | Vite dev server con HMR |
+| `bun run build` | Build a `../backend/web/` |
+| `bun run typecheck` | TypeScript type check |
+
+## API
+
+Todas las rutas bajo `/api/quotes`:
+
+| Ruta | Descripción |
+|------|-------------|
+| `GET /api/quotes` | Cotizaciones actuales |
+| `GET /api/quotes/events` | SSE — actualizaciones en vivo |
+| `GET /api/quotes/fetch` | Forzar actualización manual |
+| `GET /api/quotes/:type/history` | Historial paginado |
+| `GET /api/quotes/:type/daily` | Agregados diarios |
+| `GET /api/quotes/:type/min-max` | Mínimo y máximo diario |
+
+Tipos: `belo`, `blue`, `bna`
+
+## Docker
+
+```bash
+docker build -t personal-admin-2026 .
+docker run -p 3000:3000 \
+  -e DATABASE_URL=postgres://user:pass@host:5432/personal-admin-2026 \
+  personal-admin-2026
+```
+
+El entrypoint corre las migraciones automáticamente (con reintentos) antes de iniciar el server.
+
+## Tasks periódicas
+
+Un cron job ejecuta cada 10 minutos la consulta de las 3 cotizaciones desde fuentes externas y las persiste en la DB. Las actualizaciones se notifican a los clientes conectados via SSE.