Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ItsJhonAlex/Ecommerce/llms.txt

Use this file to discover all available pages before exploring further.

Avanzar In Time Shop is structured as a Bun workspace monorepo where every deployable surface — the REST API, the admin SPA, and the public storefront — lives under apps/, while cross-cutting concerns like the database schema and validation rules are extracted into packages/. This layout enforces clean dependency boundaries: apps consume packages, but packages never depend on apps, and the single .env file at the root is the only shared runtime configuration point.

​
Directory Structure

.
├── apps/
│   ├── backend/       # @avanzar/backend — Hono REST API
│   ├── admin/         # @avanzar/admin — React admin SPA
│   └── storefront/    # @avanzar/storefront — Astro public storefront
├── packages/
│   ├── db/            # @avanzar/db — Drizzle ORM schema + client
│   └── shared/        # @avanzar/shared — Zod schemas shared across apps
├── .env               # Single .env at monorepo root
├── docker-compose.yml # PostgreSQL service
└── package.json       # Root workspace manifest
All apps load environment variables from the single .env file at the monorepo root using the --env-file=../../.env flag. There are no per-app .env files — every variable is defined in one place.

​
Apps

@avanzar/backend

Hono v4 REST API — the authoritative backend for all data and business logic. Runs on port 3000.

@avanzar/admin

React 19 admin SPA — staff and admin interface for managing the shop. Runs on port 5174.

@avanzar/storefront

Astro v6 storefront — the customer-facing public site. Runs on port 4321.

@avanzar/shared

Zod v4 schemas — validation logic consumed by both the backend and the admin SPA.

​
Backend (@avanzar/backend)

The backend is a Hono v4 application that serves the entire API surface under the /api/v1 prefix. It mounts middleware for request logging and CORS (configured to allow credentials from the storefront and admin origins), delegates all auth-related requests at /api/auth/* to Better Auth, and exposes a /health endpoint for liveness checks. Key responsibilities:
  • Authentication — Better Auth v1 with email + password sign-in, cookie-based sessions, and three user roles: customer, staff, and admin.
  • Business logic — order creation, stock management, payment status transitions, and shipping rate resolution.
  • Validation — request bodies are validated against @avanzar/shared Zod schemas before reaching any handler.
  • Database access — all queries go through the @avanzar/db Drizzle client; no raw SQL in route handlers.
  • API docs — Swagger UI served at /api/v1/docs via @hono/swagger-ui.
The dev script runs with --hot for instant backend reloads during development.

​
Admin Dashboard (@avanzar/admin)

The admin SPA is built with React 19, bundled by Vite v8, and styled with Tailwind CSS v4. It communicates with the backend exclusively through the REST API — there is no direct database access from the admin. Key dependencies:
  • TanStack Query v5 for server state management and cache invalidation
  • Radix UI for accessible, unstyled primitive components
  • React Router v8 for client-side routing
  • Better Auth client-side SDK for session management
  • Sonner for toast notifications
  • Vitest + Testing Library for unit and component tests

​
Storefront (@avanzar/storefront)

The storefront is an Astro v6 site that handles the public-facing catalog, product detail pages, cart state, and the checkout flow. It uses Astro’s island architecture to keep the default output static or server-rendered while adding client-side interactivity only where needed. It imports validation schemas from @avanzar/shared to validate checkout payloads before they reach the API.

​
Shared Packages

​
@avanzar/db

The @avanzar/db package is the single source of truth for the database schema. It contains a Drizzle ORM schema spread across multiple files — one per domain — and exports both the schema objects and a configured postgres client instance. Schema files and their contents:
FileTables / Enums
enums.tsuser_role, product_status, order_status, payment_method, payment_status
auth.tsBetter Auth managed tables (users, sessions, accounts, verifications)
catalog.tsProducts and categories
addresses.tsCustomer addresses
orders.tsOrders and order items
payments.tsPayment records
shipping.tsProvince-based shipping rate lookup
relations.tsDrizzle query-API relation definitions
The package exposes two entry points: . for the client and schema, and ./schema for schema-only imports. drizzle-kit is scoped to this package, so all db:generate, db:migrate, db:push, and db:studio commands run from within it (proxied via root-level scripts).

​
@avanzar/shared

The @avanzar/shared package contains Zod v4 validation schemas that are consumed by both the backend (request validation) and the admin SPA (form validation). Every export is re-exported from a single src/index.ts barrel, so consumers import from @avanzar/shared without knowing the internal file layout. Modules exported:
ModulePurpose
catalog.tsProduct and category creation/update schemas
addresses.tsCustomer address schemas
checkout.tscheckoutSchema — the full checkout payload
order-status.tsOrder status transition validation
orders.tsOrder query and filter schemas
payments.tsPayment confirmation and rejection schemas
shipping.tsShipping rate upsert schemas
users.tsUser registration and profile update schemas

​
Request Flow

The following describes how a checkout submission travels through the system:
  1. Storefront collects the cart, customer details, and selected payment method, then validates the payload locally against checkoutSchema from @avanzar/shared.
  2. POST /api/v1/checkout — the validated payload is sent to the backend. Hono middleware logs the request and verifies CORS origin.
  3. Backend validation — the route handler re-validates the body against checkoutSchema. Any mismatch returns a structured 400 response before any database work begins.
  4. Price resolution — the handler fetches current product prices from the database to prevent client-side price tampering.
  5. Atomic transaction — inside a single Drizzle transaction: stock is decremented for each line item (with a conflict check to prevent overselling), an order record is inserted, and a payment record is created with status pending.
  6. Response — the new order ID and payment instructions are returned to the storefront. The order sits in pending_payment status until a staff member confirms the payment in the admin dashboard.

​
Authentication Flow

Better Auth manages the entire authentication lifecycle. The Hono entry point mounts the Better Auth handler at /api/auth/* for both GET and POST methods: 
app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw));
Session state is maintained via HTTP-only cookies. The backend defines two Hono middleware helpers used throughout protected routes:
  • requireSession — verifies that a valid session cookie is present and injects the authenticated user object into the Hono context. Returns 401 if no session is found.
  • requireAdmin — independently verifies the session and additionally checks that the user’s role is admin or staff (via isAdminRole from @avanzar/shared). Returns 401 if no session is found, 403 for authenticated users without sufficient privileges.
The three roles and their intended scopes:
RoleAccess
customerStorefront checkout, own order history
staffAdmin dashboard — order management, payment confirmation
adminFull admin dashboard access including user management and configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us