{"id":49097288,"url":"https://github.com/luisangel2895/veloura","last_synced_at":"2026-04-20T21:08:09.359Z","repository":{"id":341283061,"uuid":"1169294358","full_name":"luisangel2895/veloura","owner":"luisangel2895","description":"Production-grade luxury lingerie e-commerce built with Next.js and TypeScript. SEO-optimized, fully tested (unit + E2E), scalable architecture with modular domain structure and performance-first design.","archived":false,"fork":false,"pushed_at":"2026-04-02T23:12:20.000Z","size":13594,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T09:48:33.218Z","etag":null,"topics":["app-router","ecommerce","nextjs","performance","playwright","seo","stripe","tailwindcss","typescript","vercel","vitest","zustand"],"latest_commit_sha":null,"homepage":"https://veloura-psi.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luisangel2895.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T13:21:08.000Z","updated_at":"2026-04-02T23:12:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/luisangel2895/veloura","commit_stats":null,"previous_names":["luisangel2895/veloura"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/luisangel2895/veloura","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luisangel2895%2Fveloura","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luisangel2895%2Fveloura/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luisangel2895%2Fveloura/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luisangel2895%2Fveloura/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luisangel2895","download_url":"https://codeload.github.com/luisangel2895/veloura/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luisangel2895%2Fveloura/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32065693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T11:35:06.609Z","status":"ssl_error","status_checked_at":"2026-04-20T11:34:48.899Z","response_time":94,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app-router","ecommerce","nextjs","performance","playwright","seo","stripe","tailwindcss","typescript","vercel","vitest","zustand"],"created_at":"2026-04-20T21:08:08.690Z","updated_at":"2026-04-20T21:08:09.345Z","avatar_url":"https://github.com/luisangel2895.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/brand/veloura-logo.png\" alt=\"Veloura logo\" width=\"140\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eVeloura\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eModern editorial ecommerce built with Next.js and Stripe\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Next.js\" src=\"https://img.shields.io/badge/Next.js-App_Router-000000?style=for-the-badge\u0026logo=next.js\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-Strict-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Stripe\" src=\"https://img.shields.io/badge/Stripe-PaymentIntent-635BFF?style=for-the-badge\u0026logo=stripe\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Playwright\" src=\"https://img.shields.io/badge/Playwright-E2E-2EAD33?style=for-the-badge\u0026logo=playwright\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Vitest\" src=\"https://img.shields.io/badge/Vitest-Unit_Tests-6E9F18?style=for-the-badge\u0026logo=vitest\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Vercel\" src=\"https://img.shields.io/badge/Vercel-Deployment-000000?style=for-the-badge\u0026logo=vercel\u0026logoColor=white\" /\u003e\n\u003c/p\u003e\n\n## Live Demo\n\nProduction: [https://veloura-psi.vercel.app/en](https://veloura-psi.vercel.app/en)\n\n## Project Overview\n\nVeloura is an editorial-style ecommerce experience designed with a luxury visual language and production-focused frontend architecture. The project combines a high-fidelity storefront with a deterministic checkout flow, typed state boundaries, and platform-level tooling that reflects senior frontend engineering standards.\n\nCore product goals:\n\n- Editorial ecommerce presentation with a refined dark/light visual system\n- State-driven checkout powered by a reducer-based state machine\n- Stripe PaymentIntent integration with a server-side intent creation flow\n- CI/CD validation covering quality gates and end-to-end critical path testing\n\nThe result is a frontend that is visually polished, operationally safe, and structured to scale toward a real backend without rewriting the UI layer.\n\n## Screenshots\n\n### Home\n\n![Home](docs/screenshots/home.png)\n\n### Product Grid\n\n![Product Grid](docs/screenshots/grid.png)\n\n### Product Detail\n\n![Product Detail](docs/screenshots/product.png)\n\n### Cart\n\n![Cart](docs/screenshots/cart.png)\n\n### Checkout – Shipping\n\n![Checkout Shipping](docs/screenshots/checkout-shipping.png)\n\n### Checkout – Review\n\n![Checkout Review](docs/screenshots/checkout-review.png)\n\n### Checkout – Payment\n\n![Checkout Payment](docs/screenshots/checkout-payment.png)\n\n### Order Complete\n\n![Checkout Complete](docs/screenshots/checkout-complete.png)\n\n## Architecture\n\n\u003e **[View the full interactive architecture diagram →](https://luisangel2895.github.io/veloura/)**\n\n![Architecture](docs/architecture.png)\n\nVeloura is structured around a frontend architecture that keeps UI, domain logic, and platform concerns clearly separated:\n\n- **Next.js App Router**\n  The application uses the App Router model to organize pages, API routes, metadata, and route-level composition. This keeps the storefront, checkout, SEO metadata, and server endpoints aligned in one coherent project structure.\n\n- **Client State Management**\n  Zustand is used for global client state, specifically for cart persistence and filtering state. This keeps cross-route commerce state predictable without pushing transient UI logic into the component tree.\n\n- **Checkout Reducer / State Machine**\n  Checkout runs on a reducer-backed state machine (`shipping -\u003e payment -\u003e review -\u003e complete`). This provides explicit transitions, deterministic validation, and a safer foundation for future integrations such as webhooks, order persistence, and payment reconciliation.\n\n- **API Routes**\n  App Router route handlers power local mock catalog APIs and the Stripe PaymentIntent creation endpoint. The server computes trusted totals, validates payloads, and avoids leaking sensitive payment logic to the client.\n\n- **Stripe PaymentIntent Server-Side Flow**\n  The client mounts a payment UI and confirms payment, while the server is responsible for creating the PaymentIntent with the final amount, receipt email, and shipping details. This keeps secret handling server-only and mirrors a production payment architecture.\n\n- **CI/CD Flow (GitHub Actions -\u003e Vercel)**\n  GitHub Actions enforces required checks on pull requests and pushes to `main`, while Vercel handles preview and production deployments. This creates a clean path from validated code to deployment without manual release steps.\n\n## Tech Stack\n\n### Frontend\n\n- Next.js (App Router)\n- TypeScript (strict)\n- Zustand (state management)\n\n### Payments\n\n- Stripe (PaymentIntent API)\n\n### Testing\n\n- Vitest (unit tests)\n- Playwright (E2E critical path testing)\n\n### DevOps\n\n- GitHub Actions\n- Vercel Deployment\n\n## Local Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nRun the development server:\n\n```bash\nnpm run dev\n```\n\nRun unit tests:\n\n```bash\nnpm run test\n```\n\nRun end-to-end tests:\n\n```bash\nnpm run e2e\n```\n\nOpen Playwright in UI mode:\n\n```bash\nnpx playwright test --ui\n```\n\nOpen the Playwright HTML report:\n\n```bash\nnpx playwright show-report\n```\n\n## Environment Variables\n\n| Variable                             | Description                                                             |\n| ------------------------------------ | ----------------------------------------------------------------------- |\n| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Public Stripe key exposed to the client for loading the payment runtime |\n| `STRIPE_SECRET_KEY`                  | Server-side Stripe secret used only when creating PaymentIntents        |\n\n### Test vs Live Keys\n\n- **Test keys** should be used during local development, staging, and any non-production verification flow.\n- **Live keys** should only be configured in secure production environments such as Vercel project settings.\n- The client must only receive `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`.\n- `STRIPE_SECRET_KEY` must never be exposed in client code, browser bundles, or CI logs.\n\n## CI/CD\n\nThe project includes a professional CI pipeline designed for pull request safety and fast feedback:\n\n- **Pull request validation**\n  Every PR runs required checks before merge. The pipeline validates linting, TypeScript, unit tests, and the critical E2E commerce flow.\n\n- **Required checks**\n  The two enforced jobs are:\n  - `quality`\n  - `e2e`\n\n- **Artifact uploads**\n  The E2E workflow uploads artifacts on every run, including failures:\n  - `playwright-report/`\n  - `test-results/`\n    Unit coverage is uploaded from the quality job.\n\n- **Automatic Vercel deployment**\n  Once code is merged and the repository is connected to Vercel, deployment can proceed automatically through Vercel’s standard preview/production flow.\n\n## Performance \u0026 SEO Strategy\n\nVeloura is tuned around the metrics that matter most in a production ecommerce storefront:\n\n- **Metadata discipline**\n  App Router metadata is defined per route with canonical URLs, Open Graph, Twitter cards, dynamic product/category metadata, `robots.txt`, and a generated sitemap that covers the storefront and PDP routes.\n\n- **Structured data**\n  The app ships `Organization`, `BreadcrumbList`, and product-level JSON-LD so search engines can understand brand identity, catalog hierarchy, and PDP commerce data.\n\n- **Media optimization**\n  Product imagery uses `next/image` with responsive `sizes`, modern format optimization, eager loading only where it improves above-the-fold rendering, and branded loading states to avoid abrupt content shifts.\n\n- **Caching and revalidation**\n  Mock catalog APIs return cache headers and the main storefront routes use revalidation so content remains fast while staying compatible with ISR-style delivery.\n\n- **Security and delivery**\n  Security headers are configured in `next.config.ts`, Stripe secrets stay server-only, and static brand/video assets are served with long-lived immutable cache headers.\n\n- **Bundle awareness**\n  The config is ready for bundle inspection via `ANALYZE=true npm run build` once `@next/bundle-analyzer` is installed, allowing targeted dependency audits without affecting production builds.\n\n### Measuring With Lighthouse\n\nUse Chrome Lighthouse against the production deployment or a local production build:\n\n```bash\nnpm run build\nnpm run start\n```\n\nThen run Lighthouse on:\n\n- `/`\n- `/grid`\n- `/product/\u003cslug\u003e`\n\nTarget scores:\n\n- Performance: 95+\n- Accessibility: 95+\n- Best Practices: 95+\n- SEO: 95+\n\n## Testing Strategy\n\nThe test suite intentionally focuses on the route that matters most:\n\n- reducer and validation logic for checkout\n- cart total integrity in integer cents\n- end-to-end customer path from product selection to completed order\n\nThis keeps the suite fast, deterministic, and genuinely useful without introducing excessive mocking or low-value snapshot coverage.\n\n## Future Improvements\n\n- Stripe webhooks for post-payment reconciliation\n- Order persistence backed by a real database\n- Automated email receipts and order notifications\n- Multi-language support beyond the current UI-level selector\n- Admin dashboard for catalog, inventory, and order operations\n\n## Branch Protection Recommended\n\nRecommended GitHub branch protection for `main`:\n\n- Require status checks: `quality` and `e2e`\n- Require pull requests before merging\n- Require branches to be up to date before merge\n- Disallow direct pushes to `main`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluisangel2895%2Fveloura","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluisangel2895%2Fveloura","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluisangel2895%2Fveloura/lists"}