Skip to content

CLAUDE.md

Latest commit

 

History

History
71 lines (52 loc) · 2.93 KB

CLAUDE.md

File metadata and controls

71 lines (52 loc) · 2.93 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Personal portfolio site: tapshalkar.com. Monorepo containing infra, frontend, backend, and scheduled jobs.

Stack

Layer Tech
Frontend Next.js (App Router, output: 'export') → GCS + Cloud CDN
Backend FastAPI, Python 3.13, uv, Cloud Run (scales to zero)
Graph job Python 3.13, uv, Cloud Run Job + Cloud Scheduler (daily)
Infra Terraform (GCP)
CI/CD GitHub Actions + Workload Identity Federation
LLM Claude API (Anthropic) — graph synthesis in the scheduled job

Monorepo Layout

frontend/        # Next.js app
backend/         # FastAPI service
jobs/graph-gen/  # Cloud Run Job — fetches APIs, calls Claude, writes graph.json to GCS
infra/           # Terraform — GCS, CDN, Cloud Run, Scheduler, IAM, Artifact Registry
.github/workflows/

Key Architectural Decisions

  • Frontend is fully static — next build with output: 'export' deploys to a GCS bucket behind Cloud CDN. No Node server.
  • Knowledge graph is dynamic — graph.json lives in GCS, generated by the scheduled job, served via GET /graph on the FastAPI backend (not bundled at build time). The graph component fetches it client-side on mount.
  • Graph component requires ssr: false — uses react-force-graph-2d (D3), which needs the DOM. Always wrap with dynamic(() => import(...), { ssr: false }).
  • Stable node IDs — graph nodes use snake_case IDs (e.g. skill-python, project-xyz). The component accepts activeNodeIds: string[] for Phase 2 agent highlighting.
  • No database in Phase 1 — all persistence is GCS (static assets + generated JSON).
  • Secrets via Google Secret Manager — injected as env vars into Cloud Run at runtime. Never in Docker images or code. Local dev uses .env (gitignored).
  • Python packaging — both backend/ and jobs/graph-gen/ use pyproject.toml + uv.lock. No requirements.txt.

Development

Commands will be added here as the project is scaffolded. Expected:

# Frontend
cd frontend && npm run dev

# Backend
cd backend && uv run uvicorn app.main:app --reload

# Graph job (local test run)
cd jobs/graph-gen && uv run python main.py

Design Tokens

bg: #0d0d0d     text: #f5f5f0     muted: #444444
accent: #ef4444  font-serif: Georgia  font-mono: 'Courier New'

Homepage layout: split hero (text left, force-directed graph right), activity feed + recent posts below.

Phase 2 Notes

Phase 2 adds a "digital me" agentic chatbot:

  • FastAPI gains a /chat endpoint backed by Claude with tool use
  • Tools: search_knowledge_graph, get_github_activity, get_now_playing, etc.
  • The graph component highlights activeNodeIds returned alongside each agent response
  • Redis (Cloud Memorystore) for API response caching
  • graph.json doubles as the agent's knowledge base — design it as such from day one