feat: document frontend tooling decisions and tradeoffs

.gitignore

@@ -1,24 +1,41 @@
-# OS files
-.DS_Store
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
 
-# Editor settings
-.vscode/
-.idea/
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
 
-# Logs
-*.log
+# debug
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.pnpm-debug.log*
 
-# Environment files
-.env
-.env.*
+# env files (can opt-in for committing if needed)
+.env*
 
-# Dependencies
-node_modules/
+# vercel
+.vercel
 
-# Build output
-dist/
-build/
-out/
+# typescript
+*.tsbuildinfo
+next-env.d.ts

.prettierrc

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}

AGENTS.md

@@ -0,0 +1,5 @@
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -1,2 +1,57 @@
 # Portfolio
 
+An open source Solana portfolio tracker built with Next.js, TypeScript, and Tailwind CSS.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20.9.0+
+- npm
+
+### Setup
+
+```bash
+npm install
+npm run dev
+```
+
+The app runs at [http://localhost:3000](http://localhost:3000).
+
+## Scripts
+
+| Command | Description |
+| --- | --- |
+| `npm run dev` | Start development server |
+| `npm run build` | Create production build |
+| `npm start` | Run production server |
+| `npm run lint` | Run ESLint |
+| `npm run format` | Format code with Prettier |
+| `npm run format:check` | Check formatting without writing |
+| `npm run typecheck` | Run TypeScript type checking |
+
+## Architecture
+
+```
+src/
+├── app/            # Next.js App Router pages and layouts
+│   ├── layout.tsx  # Root layout (header + content shell)
+│   ├── page.tsx    # Home page
+│   ├── error.tsx   # Error boundary
+│   └── not-found.tsx
+├── components/     # Shared UI components
+│   ├── header.tsx  # App header with wallet placeholder
+│   └── empty-state.tsx
+├── lib/            # Utilities, services, and data logic
+└── styles/         # Shared styles (beyond Tailwind)
+```
+
+### Tech Stack
+
+- **Framework:** Next.js 16 (App Router, Turbopack)
+- **Language:** TypeScript
+- **Styling:** Tailwind CSS v4
+- **Linting:** ESLint with next config
+- **Formatting:** Prettier
+
+For details on why these tools were chosen and when to revisit, see [Frontend Tooling Decisions](docs/frontend-tooling.md).

docs/frontend-tooling.md

@@ -0,0 +1,50 @@
+# Frontend Tooling Decisions
+
+Why we picked what we picked — so future contributors don't have to guess.
+
+## Next.js 16 (App Router)
+
+Over Vite + React Router. Next.js gives us file-based routing, server/client components, and API routes in one package. The Solana ecosystem has strong Next.js support, so contributors will find plenty of reference material.
+
+## Turbopack
+
+Default bundler in Next.js 16. Fast cold starts, instant HMR, no config needed. Fall back to Webpack with `--webpack` if ever needed.
+
+## TypeScript (strict mode)
+
+Multi-contributor project — TypeScript catches integration bugs early and gives editors autocompletion for props, API types, and Solana types.
+
+## Tailwind CSS v4
+
+Styles live next to markup — no file jumping. Consistent design tokens out of the box. Good fit for dashboard-style UI. For complex patterns, extract into components rather than using `@apply`.
+
+## ESLint + Prettier
+
+Two tools, separate concerns. ESLint catches code issues (unused vars, Next.js rules). Prettier handles formatting. Keeps config simple and conflict-free.
+
+## Project Structure
+
+```
+src/
+├── app/            # Pages, layouts, error boundaries
+├── components/     # Shared UI components
+├── lib/            # Utilities, services, data fetching
+└── styles/         # Shared styles beyond Tailwind
+```
+
+## Scripts
+
+| Script | Purpose |
+| --- | --- |
+| `npm run dev` | Dev server with HMR |
+| `npm run build` | Production build |
+| `npm run lint` | ESLint checks |
+| `npm run format` | Auto-format with Prettier |
+| `npm run format:check` | Check formatting (for CI) |
+| `npm run typecheck` | Type check without emitting |
+
+## When to Revisit
+
+- Adding shared packages → consider Turborepo
+- Turbopack missing a feature → fall back to Webpack
+- Need a real backend → evaluate a separate service

eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

next.config.ts

@@ -0,0 +1,8 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+  reactCompiler: true,
+};
+
+export default nextConfig;