# qazuor/hospeda architecture

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

- Interactive diagram: https://gitdiagram.com/qazuor/hospeda
- Repository: https://github.com/qazuor/hospeda

## Overview

##### Project type and purpose
- This is a full-stack, monorepo-based tourist accommodation platform (“Hospeda”) built with TurboRepo.
- It provides a public website (Astro + React) for browsing destinations, accommodations, events, and a backend API (Node.js + Hono) for data access and admin management.

##### File structure
- Top-level “apps” folder:
- apps/api → Hono-based REST API with versioned routes (public & admin), middleware, utils, and type definitions.
- apps/web → Astro-powered SSR/SSG frontend, using React components and a TanStack‐Router data-fetching layer.
- apps/react-app-testing → sample React/Vite playground (for component testing).
- Shared “packages” folder:
- packages/db → Drizzle ORM database layer (models, migrations, seeds, service classes).
- packages/schemas → Zod validation schemas for all entities.
- packages/types → TypeScript definitions for entities and enums.
- packages/logger → centralized logging library.
- packages/utils → generic utilities.
- packages/config, typescript-config, tailwind-config, ui → shared tooling, styling, and UI primitives.
- Config & scripts: CI workflows (.github), Dockerfile.api, TurboRepo config (turbo.json), PNPM workspace.

##### README for extra clues
- Confirms tech stack: Astro + React + Tailwind on frontend, Node + Hono + Drizzle + PostgreSQL on backend.
- Mentions multi-tenant roles & permissions, migrations, seeds, and DevOps targets (Fly.io deployment).

a. Main components
- Frontend (apps/web)
- Backend API (apps/api)
- Database (PostgreSQL via packages/db)
- Shared libraries (packages/logger, schemas, types, utils, ui, config)
- External services (e.g., Fly.io hosting, Drizzle Studio)
b. Relationships & data flows
- Browser → Web (HTTP GET/POST)
- Web → API (REST calls to /v1/public & /v1/admin endpoints)
- API → DB (Drizzle ORM queries & transactions)
- API & Web → Shared packages (importing types, schemas, utils)
- API logs → packages/logger → console/file/external logging sinks
c. Architectural patterns & principles
- Monorepo with TurboRepo for builds & dependency graph
- Layered backend: middleware → routes → controllers/services → ORM
- Repository & service pattern in DB package
- Declarative component-based UI in Astro/React
- Shared contract-first validation (Zod schemas) and types across layers
d. Technologies & frameworks
- Frontend: Astro, React, TanStack Router, Tailwind CSS, Vite
- Backend: Node.js, Hono, Zod, Drizzle ORM, PostgreSQL
- Tooling: TurboRepo, PNPM, Biome (lint/format), Fly.io (deploy)

##### Key details to capture
- Versioned route separation (public vs. admin) in the API
- Middleware chain (auth, error handlers, logger)
- Drizzle ORM’s migration/seed process
- Shared Zod schemas/types ensuring contract alignment
- Monorepo build coordination (Turbo → PNPM filters)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Apps" 
        direction TB
        Web["apps/web\n(Astro + React + Tailwind)"]:::frontend
        WebConfig["astro.config.mjs\n& tailwind.config.mjs"]:::frontend
        Pages["src/pages & Layouts"]:::frontend
        Components["src/components"]:::frontend
        DataLayer["src/data & services/api.ts"]:::frontend
        StoreUtils["src/store & utils"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Services"
        direction TB
        API["apps/api\n(Node.js + Hono)"]:::api
        Entry["src/app.ts & index.ts"]:::api
        Middleware["src/middleware/auth.ts, error.ts, logger.ts"]:::api
        PublicRoutes["src/routes/v1/public"]:::api
        AdminRoutes["src/routes/v1/admin"]:::api
        APIUtils["src/utils/db.ts & response.ts"]:::api
        TypesAPI["src/types"]:::api
    end

    %% Data Layer
    subgraph "Database Layer"
        direction TB
        DBPkg["packages/db\n(Drizzle ORM)"]:::data
        DrizzleConfig["drizzle.config.ts"]:::data
        Models["src/model & schema"]:::data
        Migrations["src/migrations"]:::data
        Seeds["src/seeds"]:::data
        DBService["src/service"]:::data
    end

    %% Shared Packages
    subgraph "Shared Packages & Tooling"
        direction TB
        Schemas["packages/schemas"]:::shared
        TypesPkg["packages/types"]:::shared
        LoggerPkg["packages/logger"]:::shared
        UtilsPkg["packages/utils"]:::shared
        UI["packages/ui"]:::shared
        ConfigPkg["packages/config"]:::shared
        TailwindCfg["packages/tailwind-config"]:::shared
        TSConfig["packages/typescript-config"]:::shared
    end

    %% Orchestration & DevOps
    Turbo["turbo.json\n(TurboRepo)"]:::shared
    CI[".github/workflows"]:::shared
    DockerAPI["Dockerfile.api"]:::shared

    %% External Services
    Postgres[(PostgreSQL)]:::external
    FlyIO[("Fly.io\nHosting")]:::external
    DrizzleStudio[("Drizzle Studio")]:::external

    %% Connections
    Browser-->|"HTTP GET/POST"|Web
    Web-->|"REST calls"|API
    API-->|"ORM queries"|DBPkg
    API-->|"Imports"|Schemas
    API-->|"Imports"|TypesPkg
    API-->|"Uses"|LoggerPkg
    API-->|"Imports"|UtilsPkg
    Web-->|"Imports"|Schemas
    Web-->|"Imports"|TypesPkg
    Web-->|"Imports"|UI
    Web-->|"Imports"|TailwindCfg
    DBPkg-->|"Connects"|Postgres
    DBPkg-->|"Migrations & Seeds"|Postgres
    API-->|"Deployed to"|FlyIO
    DBPkg-->|"Schema Sync"|DrizzleStudio
    Turbo-->|"Orchestrates"|Web
    Turbo-->|"Orchestrates"|API
    Turbo-->|"Orchestrates"|DBPkg
    CI-->|"CI/CD"|FlyIO
    DockerAPI-->|"Containerize API"|API

    %% Click Events - Frontend
    click Web "https://github.com/qazuor/hospeda/tree/main/apps/web"
    click WebConfig "https://github.com/qazuor/hospeda/blob/main/apps/web/astro.config.mjs"
    click Pages "https://github.com/qazuor/hospeda/tree/main/apps/web/src/pages"
    click Components "https://github.com/qazuor/hospeda/tree/main/apps/web/src/components"
    click DataLayer "https://github.com/qazuor/hospeda/blob/main/apps/web/src/services/api.ts"
    click StoreUtils "https://github.com/qazuor/hospeda/tree/main/apps/web/src/store"

    %% Click Events - Backend
    click API "https://github.com/qazuor/hospeda/tree/main/apps/api"
    click Entry "https://github.com/qazuor/hospeda/blob/main/apps/api/src/app.ts"
    click Middleware "https://github.com/qazuor/hospeda/blob/main/apps/api/src/middleware/auth.ts"
    click PublicRoutes "https://github.com/qazuor/hospeda/tree/main/apps/api/src/routes/v1/public"
    click AdminRoutes "https://github.com/qazuor/hospeda/tree/main/apps/api/src/routes/v1/admin"
    click APIUtils "https://github.com/qazuor/hospeda/blob/main/apps/api/src/utils/db.ts"
    click TypesAPI "https://github.com/qazuor/hospeda/tree/main/apps/api/src/types"

    %% Click Events - Database Layer
    click DBPkg "https://github.com/qazuor/hospeda/tree/main/packages/db"
    click DrizzleConfig "https://github.com/qazuor/hospeda/blob/main/packages/db/drizzle.config.ts"
    click Models "https://github.com/qazuor/hospeda/tree/main/packages/db/src/model"
    click Migrations "https://github.com/qazuor/hospeda/tree/main/packages/db/src/migrations"
    click Seeds "https://github.com/qazuor/hospeda/tree/main/packages/db/src/seeds"
    click DBService "https://github.com/qazuor/hospeda/tree/main/packages/db/src/service"

    %% Click Events - Shared Packages
    click Schemas "https://github.com/qazuor/hospeda/tree/main/packages/schemas"
    click TypesPkg "https://github.com/qazuor/hospeda/tree/main/packages/types"
    click LoggerPkg "https://github.com/qazuor/hospeda/tree/main/packages/logger"
    click UtilsPkg "https://github.com/qazuor/hospeda/tree/main/packages/utils"
    click UI "https://github.com/qazuor/hospeda/tree/main/packages/ui"
    click ConfigPkg "https://github.com/qazuor/hospeda/tree/main/packages/config"
    click TailwindCfg "https://github.com/qazuor/hospeda/tree/main/packages/tailwind-config"
    click TSConfig "https://github.com/qazuor/hospeda/tree/main/packages/typescript-config"

    %% Click Events - Orchestration & DevOps
    click Turbo "https://github.com/qazuor/hospeda/blob/main/turbo.json"
    click CI "https://github.com/qazuor/hospeda/blob/main/.github/workflows/refresh-search.yml"
    click DockerAPI "https://github.com/qazuor/hospeda/blob/main/Dockerfile.api"

    %% Styles
    classDef frontend fill:#ccefff,stroke:#009,stroke-width:1px
    classDef api fill:#ccffcc,stroke:#090,stroke-width:1px
    classDef data fill:#ffddaa,stroke:#d65,stroke-width:1px
    classDef shared fill:#dddddd,stroke:#666,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#999,stroke-width:1px
```
