ResumeSite/docs/spec/ARCHITECTURE.md

ARCHITECTURE.md

System architecture for the bilingual portfolio. Companion detail specs: ROUTING_SPEC, COMPONENT_ARCHITECTURE, I18N_SPEC, DATA_MODEL, DOCKER_SPEC, DEPLOYMENT_SPEC.

---

1. System overview

                        ┌──────────────────────────── Connor's server ───────────────────────────┐
 Browser ── HTTPS ──►   │  Traefik (existing host reverse proxy, TLS; Cloudflare-fronted)        │
                        │    ├── cesnimda.co.uk/            → [site] nginx container (static)    │
                        │    ├── cesnimda.co.uk/api/contact → [contact-relay] .NET 9 container   │
                        │    └── git.cesnimda.uk            → Gitea (existing)                   │
                        │                                                                        │
                        │  docker compose stack "resumesite": site + contact-relay (+ optional   │
                        │  analytics slot)                                                       │
                        └────────────────────────────────────────────────────────────────────────┘

 Build time (CI, Gitea Actions):
   content (markdown/JSON, images) ─► Astro build ─► static dist/ ─► site image (nginx + dist)
                                                     └► budgets/tests gate the publish

Architectural style: static-first with one stateless dynamic sidecar. All pages are pre-rendered at build time (SSG). There is no runtime rendering, no database, no sessions. The only mutable runtime path is POST /api/contact, isolated in its own container so the site itself has zero attack surface beyond static file serving.

2. Repository layout (single repo: ResumeSite on git.cesnimda.uk)

ResumeSite/
├── site/                        # Astro project
│   ├── src/
│   │   ├── pages/               # route files (EN root) — see ROUTING_SPEC
│   │   │   └── no/              # Norwegian route tree (localised slugs)
│   │   ├── layouts/             # Base, Page, CaseStudy layouts
│   │   ├── components/          # see COMPONENT_ARCHITECTURE
│   │   │   ├── core/            # Header, Footer, Seo, ThemeScript, SkipLink
│   │   │   ├── home/            # Hero, ProofStrip, SkillsGrid, ProjectCards, Timeline, ContactBand
│   │   │   ├── case-study/      # TldrBox, MiniToc, DecisionList, Diagram, Gallery
│   │   │   └── ui/              # Chip, Button, SplitButton, LangSwitch, ThemeToggle, Card
│   │   ├── content/             # content collections (the bilingual data layer)
│   │   │   ├── projects/{en,no}/...
│   │   │   ├── experience/{en,no}/...
│   │   │   └── profile/{en,no}.json
│   │   ├── i18n/                # locales.ts, dictionary.{en,no}.ts, slugMap.ts, t() helper
│   │   ├── styles/              # tokens.css (design tokens), base.css, motion.css
│   │   ├── scripts/             # island helpers: observer.ts, lightbox.ts, nav.ts, form.ts, theme.ts
│   │   └── assets/              # source images, diagrams (SVG), fonts
│   ├── public/                  # CVs (pdf), favicon, robots.txt
│   └── (astro/tailwind/ts configs)
├── relay/                       # .NET 9 minimal API contact relay (own Dockerfile)
├── deploy/                      # compose files, nginx site config, env templates
├── .gitea/workflows/            # CI/CD pipelines
├── docs/                        # this spec set + phase-1 design (moved into repo at Phase 3 start)
└── tests/                       # playwright e2e (vitest lives beside site/src)

Rationale: one repo keeps content, design docs, infra and both services versioned together — appropriate for a single-owner product and makes the repo itself portfolio evidence.

3. Layered architecture of the site

┌ Content layer      markdown + JSON content collections, schema-validated (zod) — DATA_MODEL.md
├ i18n layer         locale config, slug map, typed dictionaries — I18N_SPEC.md
├ Template layer     layouts + components consume {content, locale} → HTML — COMPONENT_ARCHITECTURE.md
├ Token layer        CSS custom properties (themes) + Tailwind utilities
├ Behaviour layer    5 small TS modules (theme, nav, observer, lightbox, form) as progressive enhancement
└ Delivery layer     static dist/ in nginx container; immutable-hashed assets; long-cache headers

Dependency rule (enforced by review, mirrors the projects' clean-architecture story): templates depend on content+i18n; content depends on nothing; behaviour modules depend on DOM contracts (data-attributes), never on content. No component reads raw filesystem or hardcodes strings.

4. Key architectural decisions (ADR summary)

#	Decision	Alternative rejected	Why
A1	Full SSG, no SSR	Astro SSR/hybrid	No per-request data exists; SSR adds a Node runtime, cold-start surface, and ops burden for zero benefit
A2	Contact relay as separate container	SSR endpoint in site / SaaS form	Keeps site image immutable+static; isolates the only untrusted-input path; self-host principle
A3	Content collections in-repo	Headless CMS (Directus/Strapi/…)	Single author, git workflow is his CMS; removes a service, a database, and an attack surface
A4	CSS custom-property tokens, data-theme attribute switch	Tailwind dark: variants only	One token source drives both themes + allows no-flash inline theme script + inspectable tokens
A5	Localised slugs via explicit map module	File-name convention magic	The EN↔NO page mapping is a contract used by header switch, hreflang, sitemap — must be a single typed artifact testable in CI
A6	Behaviour as data-attribute modules	Framework islands	JS budget < 40 kB; three behaviours don't justify a runtime; escape hatch to Preact pre-authorised if one outgrows it
A7	Images processed at build	Runtime image service	Static hosting; fixed dimensions guarantee CLS 0; AVIF/WebP generated once
A8	CVs as versioned static assets in public/ with stable URLs (/cv/connor-babbington-cv-en.pdf)	External drive links	Stable recruiter-shareable URLs; git-versioned; locale-matched download logic trivial

5. Performance strategy (architecture-level)

• Budget ownership: budgets live in CI (TECH_SPEC §9); architecture guarantees they're achievable: no runtime framework, fonts subset + preloaded, hero has no image dependency for LCP (LCP element = H1 text), screenshots below fold lazy + aspect-locked.
• Caching: hashed asset filenames → Cache-Control: immutable, 1y; HTML no-cache (revalidate) so deploys are instant; CV PDFs short cache (they update).
• Critical path: inline theme-init script (tiny, blocking by design to prevent theme flash) + single CSS file per page; JS deferred entirely.
• Third-party requests: zero. No CDN fonts, no analytics beacons (unless self-hosted later), no embeds. This is both performance and the GDPR/no-cookie-banner stance.

6. Security posture

• Static site: attack surface = nginx serving files. Headers set at the site-nginx layer: CSP (no inline scripts except the hashed theme script, no external origins), HSTS (at the edge proxy), X-Content-Type-Options, Referrer-Policy, Permissions-Policy minimal.
• Relay: input validation + size caps, honeypot + minimum-fill-time trap, per-IP rate limit, SMTP credentials via env/secret (never in image), no persistence, structured minimal logging (no message bodies), runs as non-root, read-only filesystem.
• Supply chain: pnpm lockfile committed, Renovate (already familiar from InboxIntel) on the repo, images pinned by digest in compose.

7. Failure modes & degradation

Failure	Behaviour
Relay down	Form shows the fallback panel (direct e-mail + copy button) — conversion path survives
JS disabled/broken	Full content readable; nav works (plain links); no lightbox/reveals — by design (progressive enhancement)
Old cached HTML after deploy	HTML revalidates; hashed assets never mismatch
Locale content missing (build-time)	CI fails the build (parity test) — never ships a broken language