Repository navigation
v0.1.0: Storefront Foundation and Agent Ecosystem
Pre-release
Pre-release
Release v0.1.0: Storefront Foundation and Agent Ecosystem
This cut establishes the Next.js 16 storefront foundation and locks the repository agent ecosystem, development conventions, and architecture decisions.
The application runs as a clean App Router shell on port 3100 using React 19, Tailwind CSS v4, strict TypeScript, and a pre-generated OpenAPI schema. Shopper authentication, catalog data fetching, cart management, and checkout flows remain intentionally out of scope for this milestone.
Scope
| In this release | Not in this release |
|---|---|
| Next.js 16 App Router shell, React 19, React Compiler, Cache Components | Shopper authentication, session context, token refresh |
| Tailwind CSS v4 setup, base shadcn primitives, Sonner | Catalog browsing, category filters, product detail pages |
| Vitest unit suite, Playwright smoke spec, ESLint flat config | Persistent cart state and line item mutations |
| Pre-generated OpenAPI TypeScript definitions (committed) | Checkout command, idempotency handling, order polling |
| Parallel CI workflow (lint, typecheck, unit, build, audit) and Dependabot | Customer profile and order history views |
| Canonical AGENT.md, project context, conventions, quality gates, six ADRs | Standalone MSW mock preview server |
| Port 3100 configuration and API CORS origin companion alignment | Full end-to-end multi-process CI test suites |
Core Application and Shell
- Scaffolded with Next.js 16.3.4 App Router, React 19, and Tailwind CSS v4 without modifying existing repository licenses or documentation.
- Configuration in
next.config.tsenablescacheComponents,reactCompiler, andtypedRoutes. - Baseline HTTP security headers configured in
next.config.ts:X-Content-Type-Options: nosniff,Referrer-Policy: strict-origin-when-cross-origin,X-Frame-Options: DENY, andContent-Security-Policy: frame-ancestors 'none'. - Strict
script-srcCSP is omitted for now to prevent breaking upcoming theme hydration scripts. - Base shadcn UI components installed (
button,input,card,alert,sonner) using the official compiledcnutility with@/lib/utilsre-export. - Standard document scrolling preserved. Fixed viewport overflow layouts are explicitly avoided.
Tooling, Quality Gates, and CI
- Node.js runtime set to 24 with matching
.nvmrcand package engines. - Strict TypeScript configuration with
noUncheckedIndexedAccessand path alias@/*mapping tosrc/*. - ESLint flat configuration mirroring the admin dashboard standard:
typescript-eslint,react-hooks(React 19),jsx-a11y, andconsistent-type-imports. - Vitest unit testing configured with jsdom, Testing Library, and an explicit path alias resolver.
- Playwright smoke test configured for port 3100 to verify that the home shell loads.
- GitHub Actions CI pipeline executing parallel jobs for
lint,typecheck,unit-tests,build, andaudit, reporting to a unifiedciaggregator. - Dependabot configuration for automated weekly npm and GitHub Actions dependency updates.
API Integration and Contract
- OpenAPI generator script ported from the admin dashboard to
scripts/generate-api-client.js. - Generated
schema.d.tscommitted directly to the repository so continuous integration builds offline without requiring a live backend. - Companion update applied to
ecommerce-store-api:http://localhost:3100added toCORS_ALLOWED_ORIGINSacross environment templates. - Environment bootstrap script in
scripts/generate-env.jstargeting.env.localand.secrets.
Agent Ecosystem and Governance
AGENT.mdestablishes canonical governance, order of authority, and the six non-negotiable project rules.- Thin adapter files (
AGENTS.md,CLAUDE.md,.cursor/rules/agent-rules.mdc) point directly toAGENT.mdwithout duplicating policy. - Comprehensive AI guidance committed under
docs/ai/:CONVENTIONS.md,GOVERNANCE-AND-QUALITY-GATES.md, andWORKFLOW-PLAYBOOK.md. - Six architectural decision records documented under
docs/architecture/adr/:- ADR-0001: RSC catalog, browser session client, and no BFF (Accepted).
- ADR-0002: In-memory access token with HttpOnly refresh cookie (Proposed).
- ADR-0003: Single-flight silent refresh (Proposed).
- ADR-0004: No guest cart (Proposed).
- ADR-0005: Checkout order polling (Proposed).
- ADR-0006: No proxy for auth or headers (Accepted).
- Delivery roadmap updated: Phase 0 and Phase 1 marked complete in
docs/ROADMAP.md.