shawdocs
Documentation

Architecture

How the shawweb monorepo is organized: five deployed apps, five internal packages, and the boundaries between them.

Overview

The Shaw Web Solutions platform is a single pnpm + Turborepo monorepo. Packages are organized by responsibility — core foundations, reusable engines, Shaw-only internal tooling, and a reserved backend area. Each product deploys independently to its own subdomain, while shared engines live in internal workspace packages consumed as TypeScript source (via Next.js transpilePackages) — there is no separate package build step and nothing is published to npm.

Repository layout
shawweb/
├── apps/
│   ├── website/           # shawwebsolutions.com — marketing/company site
│   ├── docs/              # docs.shawwebsolutions.com — this site
│   ├── audit/             # audit.shawwebsolutions.com — Shaw SEO Audit
│   ├── studio/            # studio.shawwebsolutions.com — Shaw Image Studio
│   └── vector/            # vector.shawwebsolutions.com — Shaw Image Vector
│
├── packages/
│   ├── core/                  # @shawweb/core — design tokens & theme
│   ├── engines/
│   │   ├── image-processing/  # @shaw/image-processing — image engine
│   │   ├── vector-processing/ # @shaw/vector-processing — SVG tracing engine
│   │   └── seo-audit/         # @shaw/seo-audit — SEO auditing engine
│   ├── internal/
│   │   └── asset-pipeline/    # @shaw/asset-pipeline — internal tooling
│   └── backend/               # reserved for the upcoming backend platform

Apps

  • website — the company site. Deliberately self-contained: its theme is an adapted copy of the core tokens and it imports no workspace packages. Its production assets are generated by the asset pipeline.
  • docs — this documentation and resource hub. Consumes @shawweb/core for theming.
  • audit — Shaw SEO Audit. Consumes @shaw/seo-audit and adds a server-side Google PageSpeed / Lighthouse integration.
  • studio — Shaw Image Studio. Consumes @shaw/image-processing for server-side batch image processing.
  • vector — Shaw Image Vector. Consumes @shaw/vector-processing; vectorization runs locally in the browser in a Web Worker.

Packages

All packages are internal to the monorepo. The processing engines are framework-independent — they run in Next.js API routes, in browser Web Workers, and in plain Node scripts (the asset pipeline and the engine test suites use the same code).

  • @shawweb/core — the canonical --sw-* design-token system and theme provider/script shared by the product apps.
  • @shaw/seo-audit — fetches and analyzes a page, producing a structured, scored audit report.
  • @shaw/image-processing — sharp-based optimization, conversion, resizing, watermarking, naming, and ZIP archiving.
  • @shaw/vector-processing — the raster-to-SVG engine: analysis, palette snapping, topology-aware background removal, dense tracing, and Bézier refitting.
  • @shaw/asset-pipeline — internal tooling that orchestrates the engines plus Playwright to generate the website's production assets.

Design decisions

  • Engines never depend on a framework, so the same code powers a browser tool, an API route, and a CLI.
  • Secrets (RESEND_API_KEY, PAGESPEED_API_KEY) exist only server-side — never in client bundles, logs, or the repository.
  • The website stays dependency-free from the workspace so marketing deploys can never be broken by engine changes.
  • Honest product statuses everywhere: “Live” means publicly usable today; tools are positioned as “Try Free”.