Dashboard Project — Technical Documentation

Overview

React-based monitoring dashboard for projects: Piewell.com, Futures Screener, OpenClaw Agent, System Monitor.

Tech Stack

• Framework: React 18 + TypeScript
• Build Tool: Vite
• Styling: Tailwind CSS
• UI Components: shadcn/ui-inspired (custom)
• Data Fetching: TanStack Query (React Query)
• Charts: Recharts
• Icons: Lucide React

Project Structure

dashboard/
├── src/
│   ├── components/
│   │   ├── cards/         # Project monitoring cards
│   │   ├── modals/        # Full-screen detail views
│   │   ├── ui/            # Reusable UI primitives
│   │   ├── Header.tsx     # Top navigation
│   │   └── Footer.tsx     # Bottom info
│   ├── hooks/             # Custom React hooks
│   ├── lib/               # Utilities & API
│   ├── types/             # TypeScript definitions
│   ├── App.tsx            # Main app component
│   └── main.tsx           # Entry point
├── backend/               # Express.js API server
│   └── index.js           # API routes
├── dist/                  # Production build output
└── MIGRATION.md           # Migration history

Development

cd /home/app/dashboard
npm install
npm run dev          # http://localhost:5173
npm run build      # Production build
npm run preview    # Preview production build

API Integration

Base URL: https://dashboard.szhub.space/api

Endpoint	Method	Description
/api/health	GET	Backend status
/api/projects	GET	All projects summary
/api/projects/:id	GET	Project details
/api/system	GET	System metrics
/api/projects/:id/kanban-tasks	GET	Task board
/api/actions/restart	POST	Restart service

State Management

• Server State: TanStack Query (caching, auto-refresh)
• Client State: React useState/useContext
• Theme: localStorage + CSS classes

Styling Guidelines

Colors

• Primary: #6366f1 (indigo)
• Success: #10b981 (green)
• Danger: #ef4444 (red)
• Warning: #f59e0b (amber)

Breakpoints

• Mobile: < 768px (1 column)
• Tablet: 768px - 1024px (2 columns)
• Desktop: > 1024px (3 columns)

Card Pattern

<Card>
  <CardHeader>
    <Icon />
    <CardTitle>Title</CardTitle>
    <Badge variant="success">Status</Badge>
  </CardHeader>
  <CardContent>
    {/* KPI grid */}
  </CardContent>
  <CardFooter>
    <Button>Actions</Button>
  </CardFooter>
</Card>

Deployment

Current Setup

• Server: srv1321680
• Process Manager: PM2 (dashboard)
• Web Server: nginx (reverse proxy)
• SSL: Let's Encrypt
• URL: https://dashboard.szhub.space

Deploy Command

npm run build
pm2 restart dashboard

Environment Variables

.env.production:

VITE_API_BASE=https://dashboard.szhub.space/api

Troubleshooting

Blank Page

• Check build: npm run build completes without errors
• Check nginx: sudo nginx -t && sudo systemctl reload nginx
• Check PM2: pm2 logs dashboard

API Errors

• Verify backend: curl https://dashboard.szhub.space/api/health
• Check CORS headers in backend
• Verify API_BASE in .env

Mobile Layout Issues

• Use responsive classes: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
• Test on actual devices, not just DevTools

Related Projects

• Backend API: /home/app/dashboard/backend/
• Legacy Version: /home/app/dashboard-old/ (retention: 30 days)
• Documentation: /home/app/dashboard/MIGRATION.md

---

Created: 2026-02-25 Maintainer: Morty