Developer onboarding

Developer onboarding

Public demo

Production storefront · Production Swagger · Production OpenAPI. For experiments and fictional registrations, prefer the separate development environment below.

Opening either API domain root / redirects to /docs (Swagger UI), so Vercel dashboard domain links open interactive documentation. Use /health for liveness; the storefront is a separate project. Existing API endpoints and the OpenAPI contract are unchanged.

Hosted development environment

Use the development storefront and Swagger UI without installing Docker. Import the hosted OpenAPI contract into Postman and set the API base URL to https://vindor-api-development.vercel.app. Use fictional accounts only. These free services can take longer on the first request.

Run the local stack

Prerequisites: Git, Python 3.12, uv, and a running Docker engine with Compose. Frontend development uses Node 24.20.0 and npm 11.19.1 at this baseline; consult the repository for future updates.

git clone https://github.com/youneshenniwrites/fastapi-next-ecommerce.git
cd fastapi-next-ecommerce
make dev
make demo

make dev preserves or generates local credentials, installs locked Python dependencies, builds the API, starts PostgreSQL, applies migrations and waits for health. make demo seeds twelve fictional products only when the catalog is empty. Credentials are ignored by Git. make down stops the stack while preserving database data.

Before starting the storefront, preserve an existing .env.local, or copy the example below if it is absent. Use http://127.0.0.1:3000, matching APP_ORIGIN exactly; the example enables loopback-only HTTP sessions for local development. Start the storefront in a terminal:

cd frontend
npm ci
# Only if .env.local does not already exist:
cp -n .env.example .env.local

If .env.local already exists, merge the required local session settings into it before starting; copying with -n preserves the old file and adds nothing:

APP_ORIGIN=http://127.0.0.1:3000
ALLOW_LOCAL_HTTP_SESSIONS=true

Preserve its API_BASE_URL and other settings. Match APP_ORIGIN to the exact browser origin and port; the HTTP permission applies only to loopback development. Restart the server after updating the file, then run npm run dev.

Open the application

These links refer to the reader's own computer, and require the services to be running. They are not public deployments.

• Storefront
• Swagger UI
• ReDoc
• OpenAPI JSON
• Health

curl --fail http://localhost:8000/health
curl --fail 'http://localhost:8000/api/v1/products/?skip=0&limit=10'

Health reports process liveness. A successful catalog request also exercises the database.

Make authenticated requests

In Swagger, expand a product GET, select Try it out, then Execute. Register a fictional customer through /api/v1/auth/register. In Authorize, use its email as username and its password. Call /api/v1/auth/me to inspect the profile.

In Postman, import the running /openapi.json URL or download the checked-in snapshot. Generate a collection and set its base URL to http://localhost:8000. Login uses x-www-form-urlencoded username/password fields. Use the returned access_token as a Bearer Token for /api/v1/auth/me. Keep passwords and tokens local and out of shared exports. Use the desktop app or Desktop Agent to reach localhost.

Product writes require an admin created through the explicit CLI; public signup does not grant admin permissions. See the complete API walkthrough and troubleshooting and safe demo/admin setup.

If a port is occupied, inspect its owner instead of stopping another service. Compose supports DB_PORT and API_PORT overrides; host database settings and client URLs must match. Do not delete volumes as a startup workaround.

Browser sessions

The local environment setup above is required for session handlers. The Next.js server handles credentials and cookies; registration and login forms are available at /register and /login. The session guide documents endpoints and failure behavior.

Domain compatibility

Both VINDOR and retained FORME storefront domains are accepted through an explicit HTTPS origin allowlist. Session cookies remain host-only; sign in separately on each hostname. Development and production stay isolated. See the repository environment guide.

To roll back domain adoption, keep using the retained FORME addresses and remove the new alias from Vercel and APP_ORIGIN_ALIASES before redeploying. Do not change database identifiers or replay migrations backwards. Provider project names are display metadata; project IDs and credentials remain stable.

Create a demo account

Open development registration, use a fictional email and a unique demo-only password (8–128 characters), then follow Continue to sign in. That sign-in has no selected product, so it returns to the collection. Sign in to add on a product returns to that product and keeps the recognised collection filters. Duplicate registrations offer sign-in guidance; invalid credentials and service outages have separate messages. The API controls authentication and privileges. Choose My account after signing in to view your email and membership date, then Sign out to end the browser session. Opening /account without a valid session shows a sign-in prompt. Do not expect password reset or email verification in this increment. Registration does not automatically retry if its response is uncertain.

Account forms briefly stay disabled while their scripts load. If JavaScript is unavailable, the page explains how to enable it. Empty sign-in submissions focus the required field without sending a request; the header Sign in link does not reload an already-open login page.

Follow the complete customer account walkthrough for the expected desktop/mobile flow, failure cases, reproducible tests and the distinction between browser cookies and Swagger/Postman tokens.

Cart API

The persistent cart API is available in production following PR #79. Its migration and deployment completed successfully. Use the API walkthrough with your own fictional account on a local test stack to add, read and remove cart lines. See the cart contract for stock and concurrency semantics. Storefront cart controls are delivered in PR #80 (#72); signing into Swagger is separate from the browser session.

Framework guidance for coding agents

Read repository AGENTS.md and the relevant .agents/skills/*/SKILL.md before changing code. Framework agent guidance records the official Next.js and FastAPI sources, version-matched documentation lookup, and the project boundaries. This workflow was added in PR #83.

Keep FastAPI authoritative for authentication, ownership, stock and prices. Use the installed Next.js documentation for framework APIs rather than copying an unverified tutorial. Make small, coherent Conventional Commits with relevant checks, push verified milestones within authorization, and obtain fresh review for the final commit before merge.

Ticket references

Use VIN-<GitHub issue number> for issue keys and PR #<number> for pull requests. Use [VIN-N] [type] Description for manual PR titles. Open the description with Issue: linking the VIN key and title, Closes/Refs, then a separate Problem: line. See Testing and delivery for examples and CONTRIBUTING for the versioned convention. Keep owner-facing replies concise.