# Shinecode Architecture Decisions

This document records important decisions and their reasoning.

## ADR-001 — Independent Next.js Frontend
Use independently deployed Next.js applications with Laravel as the backend.

## ADR-002 — Laravel Remains Business Authority
Laravel remains authoritative for business rules, authorization, data integrity, payments, and booking logic.

## ADR-003 — MySQL 8 Database
Use MySQL 8 as the authoritative database. Do not use PostgreSQL.

## ADR-004 — Shinecode Is Not Pink-First
Use `#CC2949` as the primary brand accent, not as the primary environment color.

## ADR-005 — Server-First Rendering
Prefer server/static/cached rendering over unnecessary client rendering.

## ADR-006 — On-Demand Broadcast Dispatch
Customers book times, not providers. Jobs are broadcasted to all capable partners.

## ADR-007 — Service Schema (Not Product Schema)
**Date:** 2026-08-12  
**Status:** Implemented  
**Context:** Shinecode provides at-home beauty and wellness services, not physical products for sale.  
**Decision:** Use Schema.org Service type (not Product) for structured data. Include serviceType, areaServed, provider (Shinecode Organization), offers, and aggregateRating fields.  
**Consequences:** Semantically correct structured data. Better search engine understanding. No inventory/SKU confusion.

## ADR-008 — Route Group Terminology
**Date:** 2026-08-12  
**Status:** Implemented  
**Context:** Internal route group naming should reflect product architecture, not generic marketplace terminology.  
**Decision:** Use `(services)` route group instead of `(marketplace)`. Public URLs remain unchanged.  
**Consequences:** Clearer architecture. More accurate product terminology. Implementation detail does not affect public URLs.

## ADR-009 — i18n Strategy (Pending Implementation)
**Date:** 2026-08-12  
**Status:** Planned  
**Context:** Shinecode must support English and Arabic with proper RTL support.  
**Decision:** Use next-intl with explicit locale URLs (`/en/...`, `/ar/...`). Implement RTL with logical CSS properties. Localized metadata with hreflang.  
**Consequences:** Proper internationalization. SEO-friendly locale URLs. RTL support. Requires Laravel API localization support.

## ADR-010 — VPS Deployment (Not Serverless)
**Date:** 2026-08-12  
**Status:** Active  
**Context:** Shinecode infrastructure is VPS-based (WHM/cPanel on AlmaLinux).  
**Decision:** Deploy Next.js via PM2/Node on VPS. Do not use Vercel, Netlify, or serverless platforms.  
**Consequences:** Full control over deployment. Works with existing infrastructure. Requires manual PM2 management.