diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000000000000000000000000000000000..1d8435fb10190e8f70332c549da253023f48fb48
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,122 @@
+# Metrics Portal
+
+## Project Overview
+
+Full-stack application for tracking and managing proposals and onboarding metrics within the Hive ecosystem. Serves as a dashboard for:
+- Proposal management (feasibility plans, funding proposals)
+- Onboarding analytics (creator stats, user retention, blacklists)
+- Role-based user management (Admin, Project Manager, Grantee, Newbie)
+- Real-time blockchain data sync via cron jobs
+
+## Tech Stack
+
+**Backend:**
+- Node.js + TypeScript + Express.js
+- MongoDB with Mongoose
+- JWT authentication
+- @hiveio/hive-js for blockchain integration
+- node-cron for scheduled tasks
+
+**Frontend:**
+- React 18 + TypeScript
+- Vite with SWC
+- Redux Toolkit + RTK Query
+- React Router v6
+- Bootstrap 5 + Chart.js
+
+## Directory Structure
+
+```
+backend/
+├── src/
+│   ├── index.ts              # Express entry point
+│   ├── controllers/          # Business logic (user, proposal, onboarding, blacklist)
+│   ├── models/               # Mongoose schemas
+│   ├── routers/              # Express routes
+│   ├── middleware/           # Auth (requireAuth, requireRole)
+│   ├── cron_jobs/            # Scheduled sync tasks
+│   └── types/                # TypeScript interfaces
+
+frontend/
+├── src/
+│   ├── main.tsx              # React entry point
+│   ├── App.tsx               # Router configuration
+│   ├── components/           # Reusable UI (Navbar, Footer, ProposalList)
+│   ├── pages/                # Page components (Home, Proposals, Metrics)
+│   ├── redux/                # Store + RTK Query API slices
+│   ├── hooks/                # Custom hooks (useBlacklistMap, etc.)
+│   ├── types/                # TypeScript types
+│   └── utils/                # Helper methods
+```
+
+## Development Commands
+
+**Backend:**
+```bash
+cd backend
+npm install
+npm start              # Dev server with nodemon
+npm run build          # Compile TypeScript
+npm run ts.check       # Type checking only
+```
+
+**Frontend:**
+```bash
+cd frontend
+npm install
+npm run dev            # Vite dev server
+npm run build          # Production build
+npm run lint           # ESLint
+npm run preview        # Preview prod build
+```
+
+## Key Files
+
+**Configuration:**
+- `backend/vercel.json` - Deployment config with cron schedules
+- `frontend/vite.config.ts` - Vite/SWC config
+- `backend/tsconfig.json` / `frontend/tsconfig.app.json` - TypeScript configs
+
+**Entry Points:**
+- `backend/src/index.ts` - Express app, routes, MongoDB connection
+- `frontend/src/main.tsx` - React root with Redux Provider
+- `frontend/src/App.tsx` - Route definitions
+
+**API Configuration:**
+- `frontend/src/redux/api/api.ts` - RTK Query base config (points to Vercel backend)
+
+**Environment Variables:**
+- `PORT` - Server port (default: 3000)
+- `MONGO_URI` - MongoDB connection string
+- `SECRET` - JWT secret
+- `SEARCHER_KEY` - Hive Searcher API key
+
+## Coding Conventions
+
+- TypeScript strict mode enabled
+- MVC pattern: Controllers → Models → Routers
+- Interface-based types (IUser, IProposal, etc.)
+- Async/await with try-catch error handling
+- Role-based middleware for access control
+- RTK Query for API state management
+- Functional React components with hooks
+- react-window for virtualized large lists
+
+## API Routes
+
+```
+/api/user       - User management (CRUD, login, roles)
+/api/proposal   - Proposal CRUD and status updates
+/api/onboarding - Onboarding data and metrics
+/api/blacklist  - Blacklist management
+/api/search     - Hive blockchain search proxy
+```
+
+## CI/CD Notes
+
+- Deployed to Vercel (both frontend and backend)
+- Git remote: `gitlab.syncad.com:hive/metrics-portal.git`
+- Cron jobs configured in `backend/vercel.json`:
+  - Daily crons at 05:00 UTC (`/daily_crons`)
+  - Frequent onboarders on 1st & 15th monthly
+- Pre-commit hooks: ts.check, build, add-build