Hospeda is a web platform for discovering and managing tourist accommodations in Concepcion del Uruguay and the Litoral region of Argentina. Built as a TypeScript monorepo with Astro, React, Hono, Drizzle ORM, and PostgreSQL.
| Layer | Technology | Why |
|---|---|---|
| Web App | Astro 5 + React islands | Minimal JS, SSR, SEO (ADR-001) |
| Admin | TanStack Start | Type-safe routing, file-based, full React |
| API | Hono | TypeScript-first, edge-ready, Zod integration (ADR-003) |
| Database | PostgreSQL + Drizzle ORM | SQL-like API, tree-shakeable (ADR-004) |
| Auth | Better Auth | Self-hosted, role-based (ADR-002) |
| Payments | MercadoPago | Native ARS, dominant in Argentina (ADR-005) |
| Styling | Tailwind CSS v4 | Utility-first, dark mode, design tokens |
| Testing | Vitest | Fast, ESM-native, monorepo-compatible |
| Linting | Biome | Single tool for lint + format |
| Build | TurboRepo + pnpm | Fast builds, workspace isolation |
| Deployment | Vercel | Serverless, preview environments (ADR-007) |
hospeda/
├── apps/
│ ├── api/ # Hono REST API (port 3001)
│ ├── web/ # Astro public website (port 4321)
│ └── admin/ # TanStack Start admin dashboard (port 3000)
├── packages/
│ ├── auth-ui/ # Shared auth UI components
│ ├── billing/ # Billing/monetization (MercadoPago)
│ ├── biome-config/ # Shared Biome configuration
│ ├── config/ # Shared configuration
│ ├── db/ # Drizzle ORM models and schemas
│ ├── i18n/ # Internationalization (es/en/pt)
│ ├── icons/ # Icon components (Phosphor wrappers)
│ ├── logger/ # Structured logging
│ ├── notifications/ # Notification system
│ ├── schemas/ # Zod validation schemas (source of truth)
│ ├── seed/ # Database seeding
│ ├── service-core/ # Business logic (BaseCrudService)
│ ├── tailwind-config/ # Shared Tailwind configuration
│ ├── typescript-config/ # Shared TypeScript config
│ └── utils/ # Shared utilities
├── docs/ # Project documentation
└── scripts/ # Build and deployment scripts
- Node.js >= 18
- pnpm 9.x
- PostgreSQL 15+
- Docker (for local DB)
git clone https://github.com/qazuor/hospeda.git
cd hospeda
pnpm install
cp .env.example .env # Edit with your configuration
pnpm db:start # Start PostgreSQL + Redis (Docker)
pnpm db:migrate # Apply migrations
pnpm db:seed # Seed database
pnpm dev # Start all apps| Command | Description |
|---|---|
pnpm dev |
Start all apps in development |
pnpm build |
Build all packages |
pnpm test |
Run all tests |
pnpm lint |
Biome linting |
pnpm format |
Biome formatting |
pnpm typecheck |
TypeScript validation |
pnpm db:fresh |
Reset + migrate + seed database |
pnpm db:studio |
Open Drizzle Studio |
Three-tier route system:
| Tier | Pattern | Auth | Consumer |
|---|---|---|---|
| Public | /api/v1/public/* |
None | Web app |
| Protected | /api/v1/protected/* |
Session | Web app (logged in) |
| Admin | /api/v1/admin/* |
Admin + permissions | Admin panel |
- Adding New Entity
- Adding Web Pages
- Adding Admin Pages
- Adding API Routes
- Authentication
- Dependency Policy
- Branding and Theming
- All Guides
See Contributing Guide for code standards, git workflow, and PR process.
This project is licensed under the MIT License - see the LICENSE file for details.