How the platform is built.

One platform, two faces.

markus-mildner.com is a unified personal and professional platform: a public website, a blog, and a suite of private productivity tools. It serves two audiences at once — professional visitors, and Markus himself as a daily user of his own tools. The public face (homepage, blog, CV) is expressive and editorial; the private interior (tools, finance, study, settings) is denser and functional. Both share one codebase, design system, and infrastructure.

Six non-negotiable constraints.

Every technical decision is evaluated against these, in order of priority. Anything that contradicts them requires an explicit decision recorded in the guide.

The technology stack.

Each choice optimises for AI-generation quality, near-zero cost, and the fixed AWS + Terraform base.

Explicitly rejected

• ✕Vercel / Netlify — bypasses Terraform IaC; higher cost at scale.
• ✕Astro — mixed .astro/.tsx reduces AI generation clarity.
• ✕SSR by default — requires compute. output: 'export' is the default; SSR is opt-in per route.
• ✕RDS / PostgreSQL — always-on; ~€7/month minimum. DynamoDB covers all current patterns.
• ✕Prisma / GraphQL — over-abstraction for this scale. AWS SDK + REST is sufficient.
• ✕CSS Modules / Styled Components — breaks the Tailwind utility model.
• ✕any in TypeScript · Jest · Lucide — banned, replaced by Vitest, superseded by Phosphor.

One Turborepo, one-directional graph.

Apps, shared packages, Lambdas, and Terraform live in a single monorepo. Dependencies flow one way; circular imports fail the build.

apps/
  web/          # markus-mildner.com (public + tools)
  blog/         # blog.markus-mildner.com (static export)
  finance/      # finance.… (SPA, Cognito-gated)
packages/
  ui/           # Shared React components (Sol del Sur)
  tokens/       # CSS variables + TS constants
  config/       # Shared tsconfig, eslint, tailwind, vitest
  types/        # Shared interfaces + API contracts
lambdas/
  chatbot/  visitor-tracker/  contact-form/
  notifier/  config-api/
terraform/      # All AWS infra (modules + main.tf)
content-machine/ # AI blog pipeline
docs/          # design-system.md + platform-guide.md
turbo.json   package.json   # npm workspaces root

Static by default, dynamic by exception.

The baseline next.config.ts sets output: 'export' so every app deploys as pure static files to S3. Server compute is opt-in, never the default.

Does this page change per-request?
  No  → output: 'export' (default). Pure static. S3 serves it.
  Yes → Is it an API route?
        Yes → Standalone Lambda + API Gateway (not a Next API route)
        No  → Client-side data fetching (SWR) within a static shell.
              force-dynamic only as a last resort.

Server vs Client Components

Default to Server Components. Add 'use client' only at the leaves — never make a whole layout Client because one button needs onClick.

Design tokens, in code.

The Sol del Sur tokens live as CSS custom properties in packages/tokens/tokens.css and are bridged into Tailwind v4 via @theme. Every colour, spacing, type, and motion value comes from this file — never hardcoded. This is what makes AI-generated components correct by default.

/* Accent — terracotta / sol */
--color-accent:      #C8813A;   /* dark: #E09B52 */
--color-teal:        #1A7A6E;
--color-canary:      #D4A843;
/* Surfaces — warm stone */
--color-bg:          #F5F1EA;   --color-surface: #FDFAF5;
--color-text:        #2A2420;   --color-text-muted: #7A7268;
/* Fonts */
--font-serif: 'Cormorant Garamond';  --font-sans: 'Geist';
--font-mono:  'Geist Mono';          --font-serif-long: 'Lora';
/* Spacing · radius · motion */
--space-4: 16px;  --radius-btn: 6px;  --radius-card: 10px;
--ease-modal: cubic-bezier(0.2, 0, 0, 1);  --duration-smooth: 200ms;

One component anatomy.

Every shared component in packages/ui follows the same shape — so AI tools generate it correctly every time.

// 1 · named props interface, extends the native element
interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
  size?: 'compact' | 'default' | 'prominent';
}
// 2 · variant maps as const objects, not inline ternaries
const variantClasses = {
  primary:   'bg-accent text-[#FFF5EA] hover:opacity-90',
  secondary: 'border border-border-strong hover:bg-surface-2',
} as const;
// 3 · forwardRef on interactive leaves · cn() merges className last
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(...);

• ✓Named exports only — no default exports; the import name must match the component.
• ✓className contract — every component accepts className and merges it last with cn().
• ✓Barrel exports — consumers import from index.ts, never a deep file path.
• ✓Extensible Tag — four built-in variants (sol · teal · canary · neutral); custom categories registered at runtime via config (§11).

Lambdas: thin edge, pure core.

Every Lambda splits HTTP concerns from business logic. index.ts parses, validates, and shapes responses; handler.ts is a pure, fully-testable function. Secrets load once at cold start from SSM.

src/
  index.ts    # HTTP parsing, validation, response shaping
  handler.ts  # pure business logic — typed in, typed out
  types.ts    # input/output types
  lib/        # AWS SDK wrappers (ssm.ts, dynamodb.ts)
__tests__/    # handler.test.ts + index.test.ts

All infrastructure is Terraform.

Resources are never provisioned manually. A module encapsulates one reusable pattern; each app is a new instantiation, not a copy-paste. Account IDs, regions, and ARNs are never hardcoded.

Naming · {project}-{purpose}-{year}

CloudFront cache strategy

/*.html            → no-cache, no-store, must-revalidate
/_next/static/*    → public, max-age=31536000, immutable
/images, /fonts    → public, max-age=31536000, immutable
/api/*             → no-store

DynamoDB, no ORM — plus a config table.

Direct AWS SDK; types model the DynamoDB shape explicitly. Raw IPs are never stored — always a SHA-256 hash (GDPR). A dedicated markus-website-config table holds runtime settings that change without a deploy: feature flags, tag categories, site metadata, chat model selection.

PK: namespace   # "platform" | "chat" | "tags" | "features"
SK: key         # "site_title" | "model" | "custom_categories"
  value       # JSON-serialised string
  public      # readable without auth?
  updated_by  # Cognito sub (owner identity)

The /settings page (owner-only) edits each namespace independently, saving on blur with optimistic updates and rollback on error. The four built-in tag variants are never stored here — custom categories are always additive, rendered via the Tag component's dynamicStyle prop.

AI features, structured.

System prompts are TypeScript constants in packages/types/src/prompts.ts — never magic strings scattered across Lambdas. The chatbot streams responses as server-sent events.

export const handler = awslambda.streamifyResponse(async (event, stream) => {
  stream.setContentType('text/event-stream');
  const res = await anthropic.messages.stream({
    model:  'claude-sonnet-4-20250514',
    system: SYSTEM_PROMPTS.chatbot,
    messages: [{ role: 'user', content: event.body ?? '' }],
  });
  for await (const chunk of res) /* write text deltas */;
  stream.end();
});

Targeted confidence, not coverage.

One developer, personal platform — 100% coverage would waste time. Test what you cannot see at a glance: pure logic, edge cases, error handling, and shared components many surfaces depend on. Don't test that a <div> renders.

Deploy on push, secure by design.

GitHub Actions deploys on push to main. Tests, type-check, and lint gate every deploy; workflow_dispatch allows a manual redeploy from the GitHub mobile app.

push → main  ──▶  test job   # turbo type-check lint test --filter=web…
                   │
                   ▼
                deploy job  # turbo build → aws s3 sync → CloudFront invalidate

Security baseline

• ✓Secrets in SSM SecureString, fetched at cold start — never in env vars or code.
• ✓Input guards on every Lambda; length limits prevent prompt injection & runaway cost.
• ✓Config writes require a valid Cognito owner token; an owner-sub check beyond auth.
• ✓Structured JSON logging only — no console.log, no raw IPs, ever.

Naming & the 14 rules.

Conventions are enforced by ESLint and the strict type-checker so AI generation lands consistently. Components PascalCase.tsx, hooks useCamelCase.ts, types no I-prefix, constants SCREAMING_SNAKE_CASE, const-objects instead of enums.

1. TypeScript strict always on.
2. No any — narrow unknown or model it.
3. No hardcoded colour, spacing, or font values.
4. No default exports from components.
5. Every interactive element has a focus state.
6. Every icon-only button has an aria-label.
7. Every image has alt text (alt="" if decorative).
8. One h1 per page.
9. No pill buttons — rounded-btn (6px).
10. Geist is the UI font — no Inter / Roboto.
11. No console.log in Lambdas — JSON only.
12. No raw IPs stored — SHA-256 always.
13. Tests run before deploy; a failure blocks it.
14. npm audit in CI; high/critical blocks deploy.