Developer architecture

This page is secondary to the client-facing guide. It documents the build direction for developers and technical stakeholders.

Superrepo layout

The project is organized as a Bun superrepo:

• apps/web: Vite, React, React Router, Tailwind storefront
• apps/api: Hono API for checkout, inventory, auth verification, and future admin actions
• apps/docs: Fumadocs documentation site
• packages/shared: shared catalog, cart, checkout, member, and reward types

This keeps the shopper interface fast while keeping privileged work behind the API.

Why Vite and Hono

The storefront is a client-side app because the main experience is browsing, cart interaction, member login, and pickup checkout.

Vite is useful here because it gives a quick development loop and keeps product UI work simple. React Router keeps the route table readable without forcing the prototype through a full server-rendered app model.

Hono is used for the API because the sensitive boundaries are small and explicit:

• payment provider selection
• checkout session creation
• NMI sandbox sale calls
• Supabase access token verification
• future admin, rewards, and order actions

The split is intentional. The browser can present the experience, but the API decides what is trusted.

Source configuration vs environment

The app should not use environment variables for every product behavior switch.

Use source-level config for bundled product behavior:

• whether OAuth buttons are visible
• which providers are exposed
• whether rewards are visible
• which storefront features appear in the UI

Use environment variables for deployment facts:

• public API URL
• public Supabase URL
• public Supabase anon key
• server-only payment keys
• server-only Supabase verification values

This keeps HMR-friendly app behavior in TypeScript while keeping deployment-specific connection values out of source.

Self-hosted utilities

The direction is compatible with self-hosted services:

• Coolify can run the web app, API, docs, and support services.
• Supabase can provide auth and later database tables.
• Hono keeps the backend small enough to reason about.
• Fumadocs keeps client docs close to the project.

This is not meant to oversell self-hosting. It gives control and portability, but it also requires backups, monitoring, updates, and clear ownership.

Next technical steps

Good next slices:

1. Replace placeholder member data with Supabase profile and reward tables.
2. Add saved product lists behind the member API boundary.
3. Persist pickup hold requests.
4. Add staff review screens after the request data shape is stable.
5. Keep NMI payment isolated behind the provider interface until a merchant account is approved.