portfolio-monorepo

Imported from Shafnaa/portfolio-monorepo (AGENTS.md). Install upstream with npx skills add Shafnaa/portfolio-monorepo. Copyright stays with the author.

AGENTS.md

Repo Layout

• Two-area monorepo: frontend/ (React + TanStack Router + Vite) and backend/ (FastAPI + LangGraph). Keep changes in the relevant area only.
• Root package.json defines workspaces but has no scripts; all commands run inside frontend/ or backend/.
• Root bun.lock is the shared lockfile. Use bun as the package manager.

Setup & Environment

• Install: bun install from the repo root (or inside each workspace).
• OpenCode requires .env.local at the repo root. .opencode/run.sh sources it before launching opencode .; if you launch OpenCode directly and env vars are missing, run source .env.local first.
• Never read or commit .env.local; secrets live there. .env.example files document required variables.

Frontend (frontend/)

• React 19 + TanStack Router (file-based) + Vite 8 + Tailwind 4.
• Entry points: src/main.tsx, src/router.tsx, src/routeTree.gen.ts.
• Generated file: src/routeTree.gen.ts is auto-generated by TanStack Router — do not edit. Regenerate with bun run generate-routes (script in package.json).
• tsr.config.json and vite.config.ts configure the router; components.json configures shadcn/Tailwind.
• Scripts: dev (Vite on port 3000), build, generate-routes, preview.
• README.md is a generated TanStack Start template — treat as background only, not a source of truth.

Backend (backend/)

• Python 3.12, FastAPI, LangGraph/LangChain, PostgreSQL/pgvector.
• Entry point: app/main.py (FastAPI app, /health endpoint).
• dev.sh builds the frontend first, then starts uvicorn with reload on port 8080.
• pyproject.toml and requirements.txt pin dependencies; keep them in sync.
• vercel.json configures serverless function limits for deployment.
• app/agent.py contains the LangGraph agent logic; changes here affect the LLM flow.

OpenCode Project Management

• Use .opencode/agents/project-manager.md for issue creation: Epic -> Story -> Task hierarchy, no implementation detail in Stories, no Tasks until Stories are reviewed.
• Use .opencode/skills/issue-management/ for issue templates and metadata rules.
• GitHub issues are authoritative; the local .issues/ folder is a mirror refreshed with gh-issue-sync pull. Never hand-edit .issues/ files.
• Use .opencode/skills/branching-strategy/ for branch names and merge order (task -> story -> epic -> main).
• Resolve owner/repo from git remote get-url origin before every GitHub MCP call — never hardcode the repo name.

GitHub MCP

• .opencode/opencode.json configures the GitHub MCP server using a PAT from .env.local.

Verification & Workflow

• No CI, lint, or typecheck scripts are configured; verification is manual via dev/build commands.
• Frontend: bun run build from frontend/. Backend: uvicorn app.main:app --reload from backend/.
• Before editing generated files, check the relevant config (vite.config.ts, tsr.config.json, components.json).
• Keep changes scoped: frontend changes stay in frontend/, backend changes stay in backend/.