Skip to content

Commit f15a50b

Browse files
ch4r10t33rch4r10t33r
committed
feat: convert to monorepo with React web UI
Adds a complete web interface inspired by checkpointz for monitoring leanpoint checkpoint sync status and upstream lean nodes. Backend changes: - Add /api/upstreams endpoint to expose detailed upstream status - Add static file serving for web-dist/ frontend assets - Add UpstreamsData structures for API serialization - Add mutex to UpstreamManager for thread-safe access - Update AppState to reference UpstreamManager Frontend additions: - React + TypeScript + Vite setup in web/ directory - StatusCard component for overall checkpoint status - UpstreamsTable component for per-upstream monitoring - CSS theming matching checkpointz aesthetic - API client for backend communication Build system: - Add Makefile with unified build targets - Support for development workflow (make dev) - Clean separation of backend/frontend builds Documentation: - Add MONOREPO_GUIDE.md with comprehensive usage guide - Add web/README.md for frontend development - Update .gitignore for frontend artifacts
1 parent c3e1a74 commit f15a50b

24 files changed

Lines changed: 4917 additions & 1 deletion

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,8 @@ deps.zig
3232

3333
# User-specific configuration
3434
upstreams.json
35+
36+
# Frontend
37+
web/node_modules/
38+
web-dist/
39+
*.local

‎MONOREPO_GUIDE.md‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Leanpoint Monorepo Guide
2+
3+
Welcome to the new leanpoint monorepo! This guide will help you get started with both the backend and the frontend.
4+
5+
## 🎯 What's New
6+
7+
Leanpoint is now a monorepo with:
8+
9+
- **Zig Backend** (`src/`) - Fast, lightweight checkpoint sync provider
10+
- **React Frontend** (`web/`) - Modern web UI inspired by checkpointz
11+
- **Unified Build System** - Single `Makefile` to build everything
12+
13+
## 📁 Project Structure
14+
15+
```
16+
leanpoint/
17+
├── src/ # Zig backend source
18+
│ ├── main.zig # Entry point
19+
│ ├── server.zig # HTTP server + static file serving
20+
│ ├── state.zig # Application state with upstream tracking
21+
│ ├── upstreams.zig # Upstream manager
22+
│ └── ...
23+
├── web/ # React frontend
24+
│ ├── src/
25+
│ │ ├── components/ # React components
26+
│ │ ├── api/ # API client
27+
│ │ ├── types/ # TypeScript types
28+
│ │ └── App.tsx # Main app
29+
│ ├── package.json
30+
│ └── README.md
31+
├── web-dist/ # Built frontend (generated)
32+
├── Makefile # Build system
33+
└── README.md # Main documentation
34+
```
35+
36+
## 🚀 Quick Start
37+
38+
### 1. Build Everything
39+
40+
```bash
41+
make build
42+
```
43+
44+
This builds both the Zig backend and the React frontend.
45+
46+
### 2. Run the Backend with UI
47+
48+
```bash
49+
# Make sure you have an upstreams config
50+
cp upstreams.example.json upstreams.json
51+
# Edit upstreams.json as needed
52+
53+
# Run with static frontend
54+
./zig-out/bin/leanpoint --upstreams-config upstreams.json --static-dir web-dist
55+
```
56+
57+
### 3. Access the Web UI
58+
59+
Open your browser to:
60+
61+
```
62+
http://localhost:5555
63+
```
64+
65+
You should see the leanpoint dashboard with:
66+
- Real-time checkpoint status
67+
- Upstream nodes health monitoring
68+
- Consensus tracking
69+
70+
## 🛠️ Development Workflow
71+
72+
### Backend Development
73+
74+
```bash
75+
# Build only backend
76+
make build-backend
77+
78+
# Run backend
79+
./zig-out/bin/leanpoint --upstreams-config upstreams.json
80+
```
81+
82+
### Frontend Development
83+
84+
```bash
85+
# Start frontend dev server with hot reload
86+
make dev
87+
# or
88+
cd web && npm run dev
89+
```
90+
91+
The dev server runs on `http://localhost:5173` and proxies API requests to `http://localhost:5555`.
92+
93+
**Important**: Keep the backend running while developing the frontend!
94+
95+
```bash
96+
# Terminal 1: Backend
97+
./zig-out/bin/leanpoint --upstreams-config upstreams.json
98+
99+
# Terminal 2: Frontend dev server
100+
cd web && npm run dev
101+
```
102+
103+
### Production Build
104+
105+
```bash
106+
# Build everything for production
107+
make build
108+
109+
# Run with static frontend
110+
./zig-out/bin/leanpoint --upstreams-config upstreams.json --static-dir web-dist
111+
```
112+
113+
## 📡 API Endpoints
114+
115+
The backend exposes these endpoints:
116+
117+
| Endpoint | Description | Used By |
118+
|----------|-------------|---------|
119+
| `GET /status` | Current checkpoint status (JSON) | Frontend, Monitoring |
120+
| `GET /api/upstreams` | Upstream nodes data (JSON) | Frontend |
121+
| `GET /metrics` | Prometheus metrics | Monitoring |
122+
| `GET /healthz` | Health check | Load balancers |
123+
| `GET /` | Web UI (if `--static-dir` set) | Browsers |
124+
125+
## 🧪 Testing with Local Devnet
126+
127+
### 1. Start Local Lean Devnet
128+
129+
```bash
130+
cd /path/to/lean-quickstart
131+
./spin-node.sh --node all
132+
```
133+
134+
### 2. Generate Upstreams Config
135+
136+
```bash
137+
cd /path/to/leanpoint
138+
python3 convert-validator-config.py \
139+
../lean-quickstart/local-devnet/genesis/validator-config.yaml \
140+
upstreams-local.json
141+
```
142+
143+
### 3. Run Leanpoint with UI
144+
145+
```bash
146+
./zig-out/bin/leanpoint --upstreams-config upstreams-local.json --static-dir web-dist
147+
```
148+
149+
### 4. Monitor in Browser
150+
151+
Open `http://localhost:5555` and watch the dashboard update in real-time!
152+
153+
## 🎨 Customizing the UI
154+
155+
### Change Colors/Theme
156+
157+
Edit `web/src/styles/App.css`:
158+
159+
```css
160+
:root {
161+
--primary-color: #6366f1; /* Change primary color */
162+
--secondary-color: #8b5cf6; /* Change secondary color */
163+
--bg-color: #0f172a; /* Change background */
164+
/* ... more variables ... */
165+
}
166+
```
167+
168+
### Modify Components
169+
170+
- **Status Cards**: `web/src/components/StatusCard.tsx`
171+
- **Upstreams Table**: `web/src/components/UpstreamsTable.tsx`
172+
- **Main Layout**: `web/src/App.tsx`
173+
174+
## 🔧 Makefile Commands
175+
176+
| Command | Description |
177+
|---------|-------------|
178+
| `make build` | Build backend + frontend |
179+
| `make build-backend` | Build only Zig backend |
180+
| `make build-web` | Build only frontend |
181+
| `make install-web` | Install frontend dependencies |
182+
| `make dev` | Start frontend dev server |
183+
| `make run` | Run backend with UI |
184+
| `make clean` | Clean all build artifacts |
185+
| `make clean-web` | Clean only frontend artifacts |
186+
| `make help` | Show all commands |
187+
188+
## 🐛 Troubleshooting
189+
190+
### Backend won't start
191+
192+
```bash
193+
# Check if port 5555 is already in use
194+
lsof -i :5555
195+
196+
# Try a different port
197+
./zig-out/bin/leanpoint --upstreams-config upstreams.json --port 5556 --static-dir web-dist
198+
```
199+
200+
### Frontend shows "Loading..." forever
201+
202+
1. Check backend is running: `curl http://localhost:5555/status`
203+
2. Check browser console for errors
204+
3. Verify API proxy in `web/vite.config.ts`
205+
206+
### Build fails
207+
208+
```bash
209+
# Clean and rebuild
210+
make clean
211+
make build
212+
```
213+
214+
### UI not updating in dev mode
215+
216+
1. Check both backend and frontend dev server are running
217+
2. Hard refresh browser (Cmd+Shift+R or Ctrl+Shift+R)
218+
3. Check browser console for errors
219+
220+
## 📦 Deployment
221+
222+
### Docker
223+
224+
The Dockerfile already supports the monorepo structure:
225+
226+
```bash
227+
# Build image
228+
docker build -t leanpoint:latest .
229+
230+
# Run with static UI
231+
docker run -p 5555:5555 \
232+
-v $(pwd)/upstreams.json:/app/upstreams.json \
233+
leanpoint:latest \
234+
--upstreams-config /app/upstreams.json --static-dir /app/web-dist
235+
```
236+
237+
### Static Binary + Frontend
238+
239+
```bash
240+
# Build everything
241+
make build
242+
243+
# Deploy these files:
244+
# - zig-out/bin/leanpoint (backend binary)
245+
# - web-dist/ (frontend static files)
246+
# - upstreams.json (your config)
247+
248+
# Run on server
249+
./leanpoint --upstreams-config upstreams.json --static-dir web-dist
250+
```
251+
252+
## 🎯 Next Steps
253+
254+
1. **Customize the UI** - Make it your own!
255+
2. **Add more metrics** - Extend the backend API
256+
3. **Create dashboards** - Use the data for Grafana
257+
4. **Contribute** - PRs welcome!
258+
259+
## 🔗 Related Documentation
260+
261+
- Main README: `README.md`
262+
- Frontend README: `web/README.md`
263+
- Checkpointz (inspiration): https://github.com/ethpandaops/checkpointz
264+
265+
## 💡 Tips
266+
267+
- Use `make dev` for fast frontend iteration
268+
- Keep the backend running while developing
269+
- Use browser DevTools to debug API calls
270+
- Check `/metrics` endpoint for detailed stats
271+
272+
---
273+
274+
**Happy monitoring! ⚡**

‎Makefile‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
.PHONY: all build build-backend build-web install-web clean clean-web run dev help
2+
3+
all: build
4+
5+
help:
6+
@echo "Leanpoint Monorepo Build System"
7+
@echo ""
8+
@echo "Available targets:"
9+
@echo " make build - Build both backend and frontend"
10+
@echo " make build-backend - Build only the Zig backend"
11+
@echo " make build-web - Build only the frontend"
12+
@echo " make install-web - Install frontend dependencies"
13+
@echo " make dev - Run frontend dev server (hot reload)"
14+
@echo " make run - Run the backend"
15+
@echo " make clean - Clean all build artifacts"
16+
@echo " make clean-web - Clean only frontend artifacts"
17+
@echo ""
18+
19+
# Install frontend dependencies
20+
install-web:
21+
@echo "📦 Installing frontend dependencies..."
22+
cd web && npm install
23+
24+
# Build frontend (production)
25+
build-web: install-web
26+
@echo "🎨 Building frontend..."
27+
cd web && npm run build
28+
@echo "✅ Frontend built successfully to ./web-dist/"
29+
30+
# Build backend
31+
build-backend:
32+
@echo "⚡ Building Zig backend..."
33+
zig build
34+
@echo "✅ Backend built successfully to ./zig-out/bin/leanpoint"
35+
36+
# Build everything
37+
build: build-backend build-web
38+
@echo "✅ All components built successfully!"
39+
40+
# Run frontend dev server
41+
dev:
42+
@echo "🚀 Starting frontend dev server..."
43+
cd web && npm run dev
44+
45+
# Run backend
46+
run:
47+
@echo "🚀 Running leanpoint..."
48+
./zig-out/bin/leanpoint --upstreams-config upstreams.json --static-dir web-dist
49+
50+
# Clean frontend artifacts
51+
clean-web:
52+
@echo "🧹 Cleaning frontend artifacts..."
53+
rm -rf web/node_modules web-dist
54+
55+
# Clean all artifacts
56+
clean: clean-web
57+
@echo "🧹 Cleaning backend artifacts..."
58+
rm -rf zig-out zig-cache
59+
@echo "✅ All artifacts cleaned!"

‎src/main.zig‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ pub fn main() !void {
1414
var config = try config_mod.load(allocator);
1515
defer config.deinit(allocator);
1616

17-
var state = state_mod.AppState{};
17+
var state: state_mod.AppState = undefined;
1818
defer state.deinit(allocator);
1919

2020
// Check if multi-upstream mode is enabled
@@ -25,6 +25,8 @@ pub fn main() !void {
2525
return err;
2626
};
2727
defer upstreams.deinit();
28+
29+
state = state_mod.AppState.init(&upstreams);
2830

2931
std.debug.print("Loaded {d} upstreams\n", .{upstreams.upstreams.items.len});
3032
const poller_thread = try std.Thread.spawn(.{}, pollLoopMulti, .{ allocator, &config, &state, &upstreams });
@@ -33,6 +35,8 @@ pub fn main() !void {
3335
try server.serve(allocator, &config, &state);
3436
} else {
3537
// Legacy single upstream mode
38+
state = state_mod.AppState.init(null);
39+
3640
const poller_thread = try std.Thread.spawn(.{}, pollLoop, .{ allocator, &config, &state });
3741
defer poller_thread.detach();
3842

0 commit comments

Comments
 (0)