00 — MASTER SPECIFICATION — YAS.SH Enterprise Platform V3

Version: 3.0.0 · Date: 2026-08-07 · Status: Active — Single Entry Point Domain: https://yas.sh (canonical apex only — no subdomains) · Primary Dev: macOS · Prod: Oracle Linux 9 Build Philosophy: Specification → Architecture → Rules → Modules → Execution → Verification

1. Vision

Build yas.sh as a modular enterprise SaaS platform where URL shortening is the first module, not the whole product.

Future modules (without core rewrite): QR Generator · Password Tools · Bio Pages · UTM Builder · AI Tools · SEO Tools · Image Tools · API Tools · Analytics Suite

Principle: Add a feature = add a folder. Never edit core to add a tool.

2. Three Non-Negotiable Laws

These override every other instruction in this docs/ folder:

LAW OF FRESHNESS — Every dependency is the latest stable verified LIVE against its registry (pnpm view <pkg> version). No deprecated, abandoned, prerelease, or vulnerable packages. Exact pins only ("next": "15.4.2", never ^).
LAW OF PROOF — Nothing is done until a command was executed and its output is pasted in PROJECT_MEMORY.md / TEST_REPORT.md. No mocks, no stubs, no TODO, no coming soon presented as real.
LAW OF REALITY — Every feature is end-to-end: UI → API SDK → REST → Service → Prisma → MariaDB → observable result. No fake dashboards.

3. How to Read This Spec (For Humans & AI)

AI start here: Read this file FIRST, then follow the order below. Do not skip.

00_MASTER.md          ← You are here (vision + laws + workflow)
 ↓
01_ARCHITECTURE.md    → Folder structure, module system, layer diagram
02_TECH_STACK.md      → Exact stack, version floors, pnpm rules
03_DATABASE.md        → MariaDB 11 + Prisma, migrations, indexes, backup
04_API_PLATFORM.md    → API-first, OpenAPI 3.1, SDKs, auth, errors
05_UI_UX.md           → Design language (Linear/Stripe/Vercel + tools.yas.sh)
06_MODULE_SYSTEM.md   → How to create a module/tool in 1 folder
07_BLOG_SYSTEM.md     → Content Collections + MDX, SEO, images
08_SECURITY.md        → Threat model + controls + verification battery
09_TESTING.md         → Gates per phase, coverage, Lighthouse, k6
10_DEPLOYMENT.md      → macOS dev → Oracle Linux 9 prod → Docker
11_ROADMAP.md         → Phased delivery (Phase 1 = 5 features fully)
12_AI_WORKFLOW.md     → Session ritual, memory, phase gates, failure policy
13_PACKAGE_SELECTION_POLICY.md → Scoring (90+ to install)
14_PRODUCT_SPECIFICATION.md    → 50 FREE + 100 PAID feature inventory
PROJECT_MEMORY_TEMPLATE.md     → Living memory the AI updates every session
CHECKLIST.md          → Human-readable release checklist

Each doc is <250 lines, single responsibility, AI-executable.

4. Core Principles

API-first: Frontend never talks to DB, only via API SDK → REST. OpenAPI is truth.
Modular: Every feature is a module owning its UI, API, DB, tests, docs, permissions.
MariaDB 11+ primary: You already run it. Prisma ORM, versioned migrations. No second SQL.
Redis/Valkey optional: Only when needed (sessions, rate-limit, queue). Start with DB + memory.
OpenAPI is single source of truth: SDKs and docs generated from code.
Exact pinning + freshness CI: pnpm catalogs + minimumReleaseAge=1440 + renovate.
macOS first: Must run on Mac without brew (Corepack + conda/Postgres.app). Oracle second.
Documentation is product: Every endpoint has curl/JS/TS/Python/PHP/Go examples.

5. Product Shape

Free plan: 50 complete features (listed in 14_PRODUCT_SPECIFICATION.md) Paid plans: Starter / Pro / Business / Enterprise — 100 additional complete features

Every feature = UI + API + DB + Validation + AuthZ + Tests + Docs. No feature flag hiding unfinished work.

Phase 1 (this delivery):

Full design system + shell
5 features FULLY implemented end-to-end (with APIs, tests, docs)
5 blogs FULLY produced (MDX + hero/cover/thumb + SEO + JSON-LD)
Full API documentation (all endpoints documented, 5 executable)

See 11_ROADMAP.md for phased slices.

6. Repository Map

yas-enterprise-v3/
├── docs/                 ← Specification (you are here)
├── apps/
│   ├── web/              # Next.js 16 — marketing, blog, dashboard, docs UI
│   └── api/              # Hono or Next.js Route Handlers — REST /v1 + redirect
├── modules/              # ← Plugin system (see 06_MODULE_SYSTEM.md)
│   ├── links/            # { module.json, schema.ts, routes.ts, api.ts, ui/, tests/ }
│   ├── qr/
│   ├── bio/
│   └── tools/            # password, utm, base64...
├── packages/
│   ├── database/         # Prisma schema, migrations, seeds
│   ├── ui/               # Design system (shadcn)
│   ├── config/           # Shared TS/ESLint/Prettier + plans.ts
│   └── security/         # Guards, validators, CSP, rate-limit
├── blog/
│   └── content/          # MDX collections (see 07_BLOG_SYSTEM.md)
├── docker/               # Dockerfiles + compose
├── nginx/                # Nginx configs
├── scripts/              # deploy, backup, smoke, deps-check
├── PROJECT_MEMORY.md     # Living doc (from template)
└── .env.example

7. AI Workflow (Summary — details in 12_AI_WORKFLOW.md)

Every session:

Read PROJECT_MEMORY.md fully
Verify toolchain: node --version && pnpm --version && pnpm view <core> version
Pick current phase in 11_ROADMAP.md — do not jump phases
Implement vertical slice: module → API → UI → DB → tests → docs
Run gates: build + test + grep-gates + security-smoke
Update PROJECT_MEMORY.md + TEST_REPORT.md with proof
Only then close phase

If blocked: Max 5 fix attempts → record in Known Issues with full log → continue other work. Never || true, never disable a rule silently.

8. Quality Bar

Design: Linear / Vercel / Stripe / Raycast level — 2026 premium, not 2018 template
Performance: Redirect p95 <50ms cached, Marketing LCP <1.8s, Dashboard LCP <2.5s
Accessibility: WCAG 2.2 AA, 0 serious axe violations
SEO: SSR/SSG, sitemap/robots/RSS/JSON-LD, OG images, canonicals
Security: 0 high audit, gitleaks clean, SBOM shipped

9. Deliverables For This Repository

yas-enterprise-v3-production.zip (no node_modules, no .git, lockfile reproduces)
Docs: PROJECT_MEMORY.md, SECURITY.md, TEST_REPORT.md, DEPLOYMENT.md, SBOM.spdx.json

Running via:

corepack enable && pnpm install --frozen-lockfile
cp .env.example .env
pnpm build && pnpm dev  # or docker compose up

Next: Read 01_ARCHITECTURE.md.