Website Architecture

This website is a static-exported professional platform that doubles as a systems showcase. It highlights projects, writing, and proof-of-work while also exposing operational patterns (ingestion, workflow control, and AI orchestration) that are directly relevant to full-stack architecture roles.

The goal is to keep public pages fast and cacheable while delegating mutable workflows to serverless APIs. The result is a recruiter-friendly experience at the UI layer and an engineering-ready control plane behind it.

The front end is built with Next.js App Router and exported as static assets (`output: export`). Public traffic is served via CloudFront + S3. Dynamic workflows (SIWE, admin, and generation) are accessed from the browser using API Gateway-backed endpoints exposed through environment variables.

No always-on application server is required for the website shell. State-bearing operations are pushed into serverless APIs and durable storage layers.

```mermaid
flowchart LR
  Visitor[Visitor Browser] --> CF[CloudFront CDN]
  CF --> S3[S3 Static Site]
  S3 --> UI[Next.js Static UI]

  Admin[Admin Wallet User] --> SIWE[SIWE Sign-In]
  SIWE --> UI
  UI --> APIGW[API Gateway]
  APIGW --> LAMBDA[Lambda Orchestration]
  LAMBDA --> DDB[(DynamoDB State Store)]

  GH[GitHub API] --> GQL[GraphQL Fetch Script]
  GQL --> CACHE[projects.json cache]
  CACHE --> UI

  LLM[External LLM Provider] --> GEN[Generator Lambda]
  GEN --> DDB
  GEN --> S3
```

Static Website & Content: Route-level pages are generated at build time for fast delivery. Content pages remain linkable and SEO-friendly.

GitHub Projects Auto-Ingestion (GraphQL): Build step fetches repositories, normalizes metadata/tags, and emits static JSON consumed by `/projects`.

Admin Workflow Studio (content lifecycle): Wallet-gated admin pages create and track article lifecycle states (draft → review → publish).

AI Pipelines: Provider-backed generation utilities compute content outputs and pricing-aware usage metadata.

AI Labs / Agent Studio: Agent profiles define prompts, model defaults, wallet identity, and dummy cost boundaries for controlled experimentation.

```mermaid
sequenceDiagram
  participant B as Browser
  participant C as CloudFront
  participant S as S3
  participant U as Hydrated UI
  participant A as API Gateway (optional)

  B->>C: GET /website
  C->>S: Fetch static asset
  S-->>C: HTML/CSS/JS
  C-->>B: Cached response
  B->>U: Hydrate client app
  U->>A: Fetch runtime data (if needed)
  A-->>U: JSON response
```

This architecture intentionally combines static hosting primitives with targeted serverless APIs. Services are categorized below as Implemented vs Planned to keep claims precise.

DynamoDB table model (planned canonical design): workflows, content items, sessions/tokens, agent profiles, and usage logs can share PK/SK patterns for scalable access.

Current project cache strategy (implemented): GitHub repository data is normalized at build time and written to `public/projects.json`, eliminating runtime GitHub calls from the browser.

RAG-related configuration is environment-driven, allowing a vector-backed storage layer to be swapped without route changes.

```mermaid
flowchart TD
  Trigger[Build Trigger or Manual Sync] --> Script[sync-github-projects.mjs]
  Script --> GitHub[GitHub GraphQL API]
  GitHub --> Normalize[Normalize tags/categories]
  Normalize --> Cache[Write public/projects.json]
  Cache --> Render[Projects UI render]
  Render --> Visitor[Visitor sees categorized projects]
```

SIWE flow summary: wallet signs nonce challenge; verification endpoint returns session token consumed by recruiter/admin UI gates.

Session/token validation: client attaches bearer token for protected calls; backend validates token/session state before allowing writes.

Rate limiting: API Gateway throttling is assumed baseline (429 handling already wired in client). Optional WAF or DynamoDB token bucket can harden high-risk paths.

Least-privilege IAM: role scopes should isolate read-only public endpoints from mutating admin/generation workflows.

```mermaid
sequenceDiagram
  participant W as Admin Wallet
  participant UI as Admin UI
  participant S as SIWE API
  participant G as API Gateway
  participant L as Lambda Workflow
  participant D as DynamoDB

  W->>S: Sign-in (nonce + signature)
  S-->>UI: Session token
  UI->>G: Create workflow request
  G->>L: Invoke workflow handler
  L->>D: Persist initial state
  L->>L: Run generator step
  L->>D: Store outputs + status updates
  D-->>UI: Workflow status/query results
```

Static export build: CI runs project sync + Next.js build to produce `out/` artifacts.

Deployment: artifacts are uploaded to static hosting (Amplify-managed S3/CloudFront pattern). CloudFront invalidation ensures edge freshness.

API infrastructure: SAM/CloudFormation is the planned standard for repeatable Lambda + API Gateway stacks.

CloudWatch logs/metrics (planned): capture API/Lambda latency, error rates, and throttles per workflow type.

Correlation IDs (planned): propagate request IDs from UI to API logs for incident triage.

Retries/backoff (planned but recommended): use bounded exponential backoff for GitHub and LLM provider calls to absorb transient failures.

Config-driven modules: agent/team behavior loaded from typed catalogs (lib/agentsCatalog.ts, lib/pricing.ts) — no per-component conditionals.

Data-driven TypeScript typing: types inferred via typeof rawResume; adding yearsExp to resume.json propagates to SkillGroup without manual type edits.

Provider abstraction (Strategy pattern): getProvider() factory in lib/providers/index.ts swaps LLM implementations via LLM_PROVIDER env var.

Progressive disclosure: SkillDepthChart gives at-a-glance breadth/depth overview; SkillBadges below provides full enumerated detail.

Staggered Framer Motion animation: SkillDepthChart bars animate height 0 → target with per-index 80ms delay for a performant, no-layout-shift entrance.

Serverless orchestration: all state-bearing operations delegated to API Gateway → Lambda; static site shell never touches server runtime.

Separation of concerns: static Next.js export and serverless APIs are independently deployable units.

Build-time cache-ahead: GitHub API called once at prebuild, result written to public/projects.json — zero runtime cost and no token exposure to clients.

Idempotent workflow steps (planned): mutation boundaries designed so retries do not duplicate side effects.

Policy-as-code guards (planned): access and cost boundaries enforced centrally for admin and agent execution.

```mermaid
flowchart LR
  User[User selects agent] --> Estimate[Estimate tokens and USD cost]
  Estimate --> Check{Within dummy balance?}
  Check -- No --> Block[Block run and show guardrail]
  Check -- Yes --> Deduct[Deduct dummy balance]
  Deduct --> Run[Execute provider call]
  Run --> Log[Store execution log]
  Log --> Return[Return response to UI]
```

The site follows WCAG 2.1 AA guidelines and WAI-ARIA 1.1 authoring practices. All patterns below are fully implemented.

Skip link (bypass navigation): SkipLink component renders a visually hidden 'Skip to main content' link above the sticky header. CSS translateY hides it until keyboard focus; z-[100] ensures it appears above navigation. Target: id=main-content on the <main> element.

Active navigation indication (aria-current): TopNav uses usePathname() to set aria-current='page' on the active link at render time — applied to desktop links, mobile links, and dropdown items.

WAI-ARIA 1.1 tab panel (Labs Tabs): role=tablist on the container; role=tab, aria-selected, aria-controls, and id on each tab button. Inactive tabs use tabIndex=-1; focus managed programmatically. ArrowRight/ArrowLeft cycle tabs; Home/End jump to first/last.

Focus trap (modal containment): useFocusTrap hook (hooks/useFocusTrap.ts, zero-dependency) constrains Tab/Shift-Tab to focusable elements inside an open dialog. requestAnimationFrame moves initial focus after paint. Stores and restores document.activeElement on close. Respects aria-hidden subtrees.

Dialog ARIA contract: all modal overlays set role=dialog, aria-modal=true, aria-labelledby pointing to the visible title element. ESC key handler closes modals; guards busy/loading state to prevent premature close. Confirm buttons expose aria-busy during async operations.

ARIA live regions (chat): message list uses aria-live=polite so tokens are announced after streaming completes. Form carries aria-busy={isLoading}. Error messages use an always-rendered role=alert paragraph to avoid DOM insertion timing issues.

```mermaid
sequenceDiagram
  participant U as User (keyboard)
  participant T as Trigger button
  participant M as Modal dialog
  participant H as useFocusTrap hook

  U->>T: Enter / Space / Click
  T->>M: open = true
  M->>H: activate trap (enabled=true)
  H->>H: store document.activeElement
  H->>M: rAF → focus first focusable element
  U->>M: Tab / Shift+Tab
  H->>H: constrain to first↔last focusable
  U->>M: Escape key
  M->>M: open = false
  H->>H: cleanup listener
  H->>T: restore focus to trigger button
```

Intentional simplifications: lightweight SIWE session handling, public static-first architecture, and dummy balances for Agent Studio keep complexity and cost low.

Hardening roadmap: optional Cognito integration, signed API requests, stronger quota enforcement, and DynamoDB-backed token-bucket controls for abuse resistance.

Operational roadmap: formal IaC for APIs, deeper observability, and stricter workflow idempotency to support larger traffic and multi-admin teams.