uzdb/doc/README.md

# uzdb Project Documentation

## 📚 Documentation Index

This directory contains all design and specification documents for the uzdb project.

### Core Documents

| Document | Description | Status |
|----------|-------------|--------|
| [Features](./features.md) | Complete feature specification with priorities | ✅ Complete |
| [Design System](./design-system.md) | Visual design language, colors, typography, components | ✅ Complete |
| [Wireframes](./wireframes.md) | UI mockups and layout specifications | ✅ Complete |
| [User Flows](./user-flows.md) | User interaction flows and edge cases | ✅ Complete |

---

## 🎯 Project Overview

**uzdb** is a lightweight database management tool inspired by DBeaver and Navicat, built with Wails (Go + React).

### Key Characteristics
- **Lightweight**: Fast startup, minimal resource usage
- **Simple**: Focus on essential features done well
- **Modern**: Clean UI following current design trends
- **Cross-platform**: Windows, macOS, Linux support via Wails

### Tech Stack
- **Frontend**: React + TypeScript + Vite
- **Backend**: Go 1.23+
- **Desktop Framework**: Wails v2
- **Styling**: CSS Variables + modern CSS

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────┐
│           Frontend (React)              │
│  ┌──────────┬──────────┬──────────────┐ │
│  │ Sidebar  │  Editor  │   Data Grid  │ │
│  │          │          │              │ │
│  └──────────┴──────────┴──────────────┘ │
│            Wails Runtime                │
├─────────────────────────────────────────┤
│            Backend (Go)                 │
│  ┌──────────┬──────────┬──────────────┐ │
│  │  MySQL   │PostgreSQL│    SQLite    │ │
│  │  Driver  │  Driver  │    Driver    │ │
│  └──────────┴──────────┴──────────────┘ │
└─────────────────────────────────────────┘
```

---

## 📁 File Structure

```
uzdb/
├── frontend/           # React application
│   ├── src/
│   │   ├── components/ # UI components
│   │   ├── App.tsx     # Main app component
│   │   └── main.tsx    # Entry point
│   └── package.json
├── doc/               # This directory - design docs
│   ├── features.md
│   ├── design-system.md
│   ├── wireframes.md
│   ├── user-flows.md
│   └── README.md      # This file
├── internal/          # Go backend code
├── main.go            # Go entry point
└── wails.json         # Wails configuration
```

---

## 🎨 Quick Reference

### Color Palette
- **Primary**: `#3b82f6` (Blue)
- **Success**: `#10b981` (Green)
- **Warning**: `#f59e0b` (Amber)
- **Error**: `#ef4444` (Red)

### Keyboard Shortcuts
| Action | Shortcut |
|--------|----------|
| Run query | `Ctrl/Cmd + Enter` |
| New connection | `Ctrl/Cmd + N` |
| Save | `Ctrl/Cmd + S` |
| Find | `Ctrl/Cmd + F` |
| Close tab | `Ctrl/Cmd + W` |

### Supported Databases
- ✅ MySQL 5.7+
- ✅ PostgreSQL 12+
- ✅ SQLite 3.x

---

## 👥 Team Roles

### UI/UX Designer
- Responsible for visual design and user experience
- Maintains design system consistency
- Creates wireframes and prototypes

**See:** [.qoder/agents/uiux-designer.md](../.qoder/agents/uiux-designer.md)

### Frontend Developer
- Implements React components
- Integrates with Wails runtime
- Ensures responsive design

### Backend Developer
- Implements database drivers
- Handles Go business logic
- Manages connections and queries

---

## 📋 Development Workflow

### 1. Design Phase
1. Review feature requirements
2. Create/update wireframes
3. Define component specs
4. Get team approval

### 2. Implementation Phase
1. Create React components
2. Implement Go handlers
3. Write tests
4. Integration testing

### 3. Review Phase
1. Design review against specs
2. Code review
3. QA testing
4. Bug fixes

---

## 🔗 Related Resources

### Design Tools
- [Figma](https://figma.com/) - UI design and prototyping
- [Lucide Icons](https://lucide.dev/) - Icon library
- [Inter Font](https://rsms.me/inter/) - Primary typeface

### Development
- [Wails Documentation](https://wails.io/docs/)
- [React Docs](https://react.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

### Inspiration
- [DBeaver](https://dbeaver.io/) - Feature reference
- [Navicat](https://www.navicat.com/) - UX reference
- [TablePlus](https://tableplus.com/) - Modern design reference

---

## 📝 Contributing

When adding new features:

1. **Update documentation** in this directory
2. **Follow design system** for consistency
3. **Consider accessibility** requirements
4. **Test with real data** before merging

---

## 📞 Contact

For questions about design or features:
- Open an issue on GitHub
- Tag @uiux-designer for design questions
- Tag @maintainer for feature discussions

---

*Last updated: 2026-03-29*