OpticWorks Store Overview
The OpticWorks Store is our production e-commerce platform for selling mmWave presence sensors and accessories. It combines a modern Next.js 15 storefront with a Medusa v2 backend.
Live URLs
Section titled “Live URLs”| Environment | URL | Purpose |
|---|---|---|
| Production Store | optic.works | Customer-facing store |
| Admin Dashboard | api.optic.works | Order management |
| Staging Store | staging.optic.works | QA testing |
What Does the Store Do?
Section titled “What Does the Store Do?”The OpticWorks Store handles the complete customer journey:
- Product Discovery - Browse our mmWave sensor products
- Cart Management - Add items, apply discounts
- Checkout - Secure payment via Stripe
- Order Fulfillment - Automated shipping label generation
- Tracking - Real-time shipment tracking
- Email Notifications - Order confirmation, shipping updates
Technology Stack
Section titled “Technology Stack”Frontend (Storefront)
Section titled “Frontend (Storefront)”| Technology | Purpose |
|---|---|
| Next.js 15 | React framework with App Router |
| React 19 | UI components |
| Tailwind CSS 4 | Styling |
| Shadcn UI | Component library |
| Cloudflare Workers | Edge deployment |
Backend (Medusa)
Section titled “Backend (Medusa)”| Technology | Purpose |
|---|---|
| Medusa v2 | E-commerce engine |
| PostgreSQL 17 | Primary database |
| Redis 7 | Caching and sessions |
| Node.js 20 | Runtime |
| Hetzner Cloud | Infrastructure |
Integrations
Section titled “Integrations”| Service | Purpose |
|---|---|
| Stripe | Payment processing |
| EasyPost | Shipping rates and labels |
| Resend | Transactional emails |
| Hookdeck | Webhook management |
Architecture Overview
Section titled “Architecture Overview”┌─────────────────────────────────────────────────────────────────┐│ Customer Browser │└───────────────────────────────┬─────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Cloudflare Workers ││ (Next.js Storefront) ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ ││ │ Product │ │ Cart │ │ Checkout │ ││ │ Pages │ │ Logic │ │ Flow │ ││ └─────────────┘ └─────────────┘ └─────────────────────────┘ │└───────────────────────────────┬─────────────────────────────────┘ │ API Calls ▼┌─────────────────────────────────────────────────────────────────┐│ Hetzner Cloud ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Medusa v2 │ ││ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ ││ │ │ Orders │ │ Products │ │ Fulfillment │ │ ││ │ │ Service │ │ Service │ │ Service │ │ ││ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ ││ └─────────────────────────────────────────────────────────┘ ││ │ │ ││ ▼ ▼ ││ ┌─────────────────┐ ┌─────────────────────────┐ ││ │ PostgreSQL 17 │ │ Redis 7 │ ││ └─────────────────┘ └─────────────────────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ┌─────────────────┼─────────────────┐ ▼ ▼ ▼ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ Stripe │ │ EasyPost │ │ Resend │ │ Payments │ │ Shipping │ │ Emails │ └───────────┘ └───────────┘ └───────────┘Key Features
Section titled “Key Features”Product Catalog
Section titled “Product Catalog”- Multiple product variants (colors, bundles)
- Inventory tracking
- Product images via Cloudflare Images
- SEO-optimized product pages
Shopping Cart
Section titled “Shopping Cart”- Persistent cart across sessions
- Guest checkout support
- Discount code application
- Real-time inventory validation
Checkout Flow
Section titled “Checkout Flow”- Stripe Elements integration
- Deferred payment intent pattern
- Address validation
- Real-time shipping rate calculation
Order Fulfillment
Section titled “Order Fulfillment”- Automatic shipping label generation
- EasyPost rate shopping
- Tracking number sync
- Fulfillment status updates
Email Notifications
Section titled “Email Notifications”- Order confirmation
- Shipping confirmation with tracking
- Delivery notifications
- Review requests
Repository Structure
Section titled “Repository Structure”opticworks-store/├── apps/│ └── storefront/ # Next.js frontend│ ├── app/ # App Router pages│ ├── components/ # React components│ └── lib/ # Utilities├── packages/│ └── medusa-backend/ # Medusa customizations│ ├── src/│ │ ├── api/ # Custom API routes│ │ ├── jobs/ # Background jobs│ │ ├── services/ # Custom services│ │ └── subscribers/ # Event handlers│ └── medusa-config.ts├── infra/│ └── ansible/ # Deployment playbooks├── e2e/ # Playwright tests├── docs/ # Documentation└── pnpm-workspace.yamlWho Works on This
Section titled “Who Works on This”| Role | Responsibility |
|---|---|
| Frontend Engineers | Next.js storefront, UI/UX |
| Backend Engineers | Medusa customizations, integrations |
| DevOps | Infrastructure, deployments |
| Product | Catalog management, pricing |
Getting Started
Section titled “Getting Started”- Review the Architecture documentation
- Set up your Development Environment
- Understand Deployment & Operations
Resources
Section titled “Resources”- Repository: github.com/r-mccarty/opticworks-store
- Slack Channel:
#web-engineering - Admin Access: Request via IT ticket
- Stripe Dashboard: dashboard.stripe.com