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 is loaded from typed data catalogs instead of hard-coded conditionals.

Event-driven/serverless orchestration: workflows are modeled as API-triggered units that can evolve independently.

Separation of concerns: static UI and orchestration APIs are independently deployable.

Idempotent workflow steps: mutation boundaries are designed so retries do not duplicate side effects.

Policy-as-code guards: access/cost boundaries can be enforced centrally rather than per-component.

```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]
```

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.