# Architecture — CTP > **Status:** v0.1 (draft) · **Date:** 2026-10-16 · See [PRD.md](PRD.md) · [DESIGN.md](DESIGN.md) · [TASKS.md](TASKS.md) ## 1. Stack | Layer | Choice | Why | |---|---|---| | Language | **PHP 8.4** | Same as the shared hosting. | | Framework | **Laravel 13** | Same major version as the CTP SaaS project. | | Admin | **Filament 5** at `/admin` | Forms, tables, rich editor and widgets out of the box. Teal and slate theme. | | Admin auth | **Laravel Socialite** (Google) and an email allow-list | No passwords to leak. | | Public frontend | **Blade + Tailwind CSS v4 + Alpine.js** (plugins: collapse, focus) | Server-rendered HTML for SEO, a tiny JS bundle, and no Node needed at runtime. Not Inertia/Vue: the public site is content, not an app. | | Typography | `@tailwindcss/typography` (themed `prose`) | Article body. | | Icons | Lucide (`mallardduck/blade-lucide-icons`) | Same icon set as the SaaS. | | Editor | Filament **RichEditor (TipTap)**, stored as **JSON**, with custom blocks and tools (see §5.1) | Decided by the spike T0.12 (D16). TinyMCE isn't needed. | | Syntax highlighting | **`tempest/highlight`** (PHP, server-side) | No client JS. Works on shared hosting. Output is cached. | | Images | **`intervention/image` v3 (GD driver)** | WebP variants and OG image generation without Imagick or Chrome. | | Search | MySQL **FULLTEXT** through Laravel Scout's `database` engine | No external service. Enough for hundreds of articles. | | HTML sanitising | `symfony/html-sanitizer` | Editor output and comments. | | Page cache | `spatie/laravel-responsecache` (file store) | Big performance win on shared hosting. | | Sitemap | `spatie/laravel-sitemap` | | | Feeds | `spatie/laravel-feed` | RSS and Atom. | | Backups | `spatie/laravel-backup` | Off-site, every day. | | Bot protection | Cloudflare **Turnstile** | Comments. | | Tests | **Pest**, plus Larastan and Pint | Same tooling as the SaaS. | | Build | **Vite** (`laravel-vite-plugin`, `@tailwindcss/vite`) | Built in dev or CI. Only `public/build` is shipped. | ## 2. High-Level Diagram ``` Browser ──► nginx/Apache (shared host) ──► Laravel ├─ Public (Blade) ── ResponseCache ──► MySQL ├─ /admin (Filament, Google OAuth) ├─ /sitemap.xml, /feed, /llms.txt, /*.md └─ Scheduler (cron every minute) ├─ publish scheduled articles ├─ queue:work --stop-when-empty (image variants, OG images, IndexNow, mail) ├─ sitemap regenerate (when dirty) └─ backup:run (daily) ``` ## 3. Directory Layout ``` ctp/ ├─ docker/ # php (8.4-fpm), nginx, mysql config ├─ docker-compose.yml ├─ dev # helper script: ./dev up|down|artisan|composer|npm|test|lint|stan|mysql|legacy-import ├─ docs/ # PRD, ARCHITECTURE, DESIGN, TASKS ├─ legacy/ # the legacy .sql dumps (git-ignored) └─ (Laravel app at the repo root: simpler for cPanel Git and .cpanel.yml) ├─ app/ │ ├─ Filament/ # Resources: Articles, Categories, Tags, Series, Media, Comments, Projects, Pages, Redirects, NotFoundLogs, Settings │ ├─ Content/ # Rendering pipeline (see §5): HtmlSanitizer, CodeHighlighter, TocBuilder, ImageResolver, MarkdownExporter │ ├─ Seo/ # MetaBuilder, JsonLd/*, OgImageGenerator, IndexNow │ ├─ Media/ # Uploader, VariantGenerator, UsageTracker │ └─ Legacy/ # LegacyImporter, HtmlCleaner, RedirectMapper ├─ resources/views/ │ ├─ layouts/ # app (3-col), reading (1-col), base │ ├─ components/ # header, footer, theme-toggle, search-palette, toc, code-block, callout, card… │ └─ pages/ └─ resources/css/app.css # tokens shared with the CTP SaaS (DESIGN.md) ``` ## 4. Database Schema (MySQL) ``` users id, name, email (unique), google_id, google_avatar, last_login_at, -- author profile (AUTHOR-02) display_name, slug (unique), avatar_path, job_title, bio_short, bio_long, website_url, socials (json {github,x,linkedin,youtube,…}), timestamps articles id, type enum(tutorial,blog), author_id → users, title, slug (unique per type), excerpt, tldr (text), body (longtext, sanitised HTML), body_rendered (longtext, cached), toc (json), featured_media_id, category_id (null for blog), series_id, series_position, status enum(draft,scheduled,published), published_at, content_updated_at, difficulty enum(beginner,intermediate,advanced) null, reading_minutes, reading_minutes_override, prerequisites (json), repo_url, demo_url, faq (json), is_featured, is_pinned, needs_review, comments_enabled, views (unsigned int), kudos (unsigned int), legacy_id, timestamps, softDeletes FULLTEXT(title, excerpt, body_text) -- body_text = stripped plain text article_revisions id, article_id, title, body, tldr, created_at, is_autosave categories id, parent_id, name, slug (unique), description, icon, technology_id (logo), sort, seo_title, seo_description, timestamps technologies id, name, slug (unique), icon_type (simple|media|lucide), icon (Simple Icons slug or Lucide name), icon_media_id, color (brand hex), website_url, timestamps article_technology id, article_id, technology_id, version (= "Tested with"), sort -- first row = main logo in lists project_technology project_id, technology_id, sort tags id, name, slug (unique), description, timestamps article_tag article_id, tag_id series id, title, slug, description, cover_media_id, sort, timestamps projects id, title, slug, tagline, body (TipTap json), body_rendered, toc (json), cover_media_id, gallery (json [{media_id, caption}]), stack via project_technology, status (active|maintained|archived), live_url, repo_url, started_at, ended_at, is_featured, is_published, sort, timestamps project_article project_id, article_id, sort -- related tutorials, in reading order pages id, title, slug, excerpt, body (TipTap json), body_rendered, toc (json), template (default|toc|about|wide), is_published, sort, timestamps media id, folder_id, disk, path, filename, mime, size, width, height, alt, title, caption, credit, variants (json), hash (sha1, for dedupe), timestamps media_folders id, parent_id, name, timestamps media_usages media_id, usable_type, usable_id -- "Used in" + delete protection seo_meta id, seoable_type, seoable_id, title, description, keywords, canonical, robots, og_media_id comments id, article_id, parent_id, author_name, author_email, author_url, body, status enum(pending,approved,spam), is_author, ip_hash, user_agent, timestamps redirects id, from_path (unique), to_path, status_code (301|302|410), hits, last_hit_at, source enum(manual,legacy,slug), timestamps -- slug = auto from SLUG-03 not_found_logs id, path_hash (unique), path, hits, referrer (latest external), is_bot, ignored, first_seen_at, last_seen_at -- scanner noise is not logged; pruned after 90 days article_views article_id, viewed_on, visitor_hash (HMAC of IP + UA) -- per-visitor dedupe, kept one day article_view_stats article_id, date, views -- daily rollups for the dashboard article_kudos article_id, visitor_hash, created_at settings group, name, payload (json), locked -- spatie/laravel-settings (cached; turnstile secret encrypted) groups: general, seo, notice (topbar), ribbon (title, link, new_tab, bg_color, text_color auto), social, scripts, integrations, contact root_slugs slug (unique), sluggable_type (article|page), sluggable_id -- D9 shared root namespace contact_messages id, topic enum(general,tutorial_question,collaboration,speaking,bug_report,other), name, email, company, article_url, message, status enum(new,read,replied,archived,spam), ip_hash, user_agent, consent_at, replied_at, reply_body, timestamps -- purged after 12 months menus id, location (unique: header, footer_1, footer_2, footer_3, legal), name, timestamps menu_items id, menu_id, parent_id (max depth 2), sort, label, type enum(url,route,article,category,tag,series,page,project), linkable_type, linkable_id (null for url/route), url, route_name, target enum(_self,_blank), icon, badge, css_class, is_enabled, timestamps ``` ## 5. Content Rendering Pipeline The editor HTML is processed **once on save**, never on every request: 1. **Sanitise** with `symfony/html-sanitizer` using an allow-list of tags, attributes and our custom block markup. 2. **Normalise headings**: H1 becomes H2, and every H2/H3 gets a slug `id`, deduped. 3. **Build the TOC** from H2/H3 and store it in `articles.toc` (JSON). 4. **Highlight code**: `
` becomes `tempest/highlight` output with the copy button and label markup.
5. **Resolve images**: a `data-media-id` reference becomes `` from the media variants. The first image is `fetchpriority="high"`.
6. **Expand custom blocks**: callout, code tabs, steps and YouTube (lite embed).
7. **Exports**: `body_text` (plain, for FULLTEXT and the word count) and a Markdown version, which is generated on demand and cached.

The result is stored in `body_rendered`. Pages and projects use the same editor and pipeline through the `HasRenderedBody` trait. After pipeline changes, `php artisan ctp:rerender` re-renders articles, pages and projects (`--only=page` to narrow it).

### 5.1 Editor (spike T0.12, 2026-10-16, decision D16)

**Filament 5 RichEditor** (TipTap). The editor state is stored as **TipTap JSON** (`->json()`). The render pipeline produces the HTML.

What was verified by round-tripping 4 real legacy articles (ids 9, 30, 45, 66) through the editor schema (HTML → JSON → HTML):

| Content | Result |
|---|---|
| Paragraphs, `
`, ``, links, images, tables (30 cells) | Kept exactly |
| Code text inside `
` | **Identical**. Only `\r\n` becomes `\n`, which is what we want |
| Code language | **Lost** in the legacy form `
` (Prism style). It **is kept** when on ``, so the converter moves it (§10.3) |
| Inline `style`, `` | Dropped. Fine, because the converter strips them anyway |
| `