Cursor rule

1---
2alwaysApply: true
3---
4 
5# 🍽️ POS System - Complete Architecture Guide
6 
7## 🎯 Project Overview
8 
9This is a **modern, enterprise-grade Point of Sale system** built with cutting-edge technologies:
10 
11### 🏗️ Technology Stack
12- **Backend:** Golang 1.21+ + Gin framework + PostgreSQL with optimized raw SQL
13- **Frontend:** React 18.3+ + TanStack Start + TypeScript 5.6+ + Tailwind CSS + shadcn/ui
14- **Database:** PostgreSQL 15 with comprehensive schema, indexes, and constraints
15- **Infrastructure:** Docker containers with multi-stage builds and Docker Compose orchestration
16- **Authentication:** JWT-based auth with role-based access control (RBAC)
17 
18### 🚀 Core Business Features
19- **Multi-Role Support:** Admin, Manager, Server, Counter, Kitchen interfaces
20- **Complete Order Lifecycle:** Creation → Kitchen → Payment → Completion
21- **Real-time Updates:** WebSocket-like updates across all interfaces
22- **Advanced Admin Tables:** Professional data tables with sorting, filtering, pagination
23- **Payment Processing:** Multi-step payment flow with receipt generation
24- **Kitchen Display System:** Real-time order preparation workflow
25- **Table Management:** Advanced seating and table assignment system
26 
27## 📁 Project Structure
28 
29### 🏠 Root Level Files
30- [Makefile](mdc:Makefile) - **PRIMARY DEV TOOL** - All development commands (`make dev`, `make backup`, etc.)
31- [docker-compose.dev.yml](mdc:docker-compose.dev.yml) - Development environment with hot reloading
32- [docker-compose.yml](mdc:docker-compose.yml) - Production orchestration
33- [README.md](mdc:README.md) - Complete project documentation with screenshots
34- [ROLE_BASED_IMPLEMENTATION.md](mdc:ROLE_BASED_IMPLEMENTATION.md) - Role system implementation guide
35 
36### 🔧 Backend Structure (`backend/`)
37- [main.go](mdc:backend/main.go) - Application entry point, CORS, middleware setup
38- [go.mod](mdc:backend/go.mod) - Go 1.21+ dependencies (Gin, PostgreSQL driver, JWT)
39- [Dockerfile](mdc:backend/Dockerfile) + [Dockerfile.dev](mdc:backend/Dockerfile.dev) - Multi-stage container builds
40- **`internal/`** - Clean Go architecture following best practices:
41  - **[api/routes.go](mdc:backend/internal/api/routes.go)** - RESTful API route definitions with role-based grouping
42  - **[models/models.go](mdc:backend/internal/models/models.go)** - Complete data models, DTOs, and API response structures
43  - **[database/connection.go](mdc:backend/internal/database/connection.go)** - PostgreSQL connection with pooling
44  - **[middleware/auth.go](mdc:backend/internal/middleware/auth.go)** - JWT authentication + RBAC middleware
45  - **`handlers/`** - Domain-specific HTTP handlers:
46    - [auth.go](mdc:backend/internal/handlers/auth.go) - Login, logout, user management
47    - [orders.go](mdc:backend/internal/handlers/orders.go) - Complete order lifecycle management
48    - [products.go](mdc:backend/internal/handlers/products.go) - Menu and category management
49    - [tables.go](mdc:backend/internal/handlers/tables.go) - Table and seating management
50    - [payments.go](mdc:backend/internal/handlers/payments.go) - Payment processing and history
51 
52### ⚛️ Frontend Structure (`frontend/`)
53- [package.json](mdc:frontend/package.json) - React 18.3+, TypeScript 5.6+, TanStack ecosystem
54- [vite.config.ts](mdc:frontend/vite.config.ts) - Vite + TanStack Start configuration
55- [tailwind.config.js](mdc:frontend/tailwind.config.js) - Tailwind CSS + shadcn/ui theme configuration
56- [Dockerfile](mdc:frontend/Dockerfile) + [Dockerfile.dev](mdc:frontend/Dockerfile.dev) - Nginx + Node.js containers
57- **`src/`** - Modern React application structure:
58  - **[main.tsx](mdc:frontend/src/main.tsx)** - React 18 entry point with StrictMode
59  - **[index.css](mdc:frontend/src/index.css)** - Global styles and CSS variables
60  - **Core Architecture:**
61    - **[types/index.ts](mdc:frontend/src/types/index.ts)** - Comprehensive TypeScript definitions
62    - **[api/client.ts](mdc:frontend/src/api/client.ts)** - Axios-based API client with interceptors
63    - **[lib/utils.ts](mdc:frontend/src/lib/utils.ts)** - Utility functions (cn, date formatters, etc.)
64    - **[lib/form-schemas.ts](mdc:frontend/src/lib/form-schemas.ts)** - Zod validation schemas
65  - **UI Components:**
66    - **[components/ui/](mdc:frontend/src/components/ui/)** - shadcn/ui base components (Button, Card, Table, etc.)
67    - **[components/forms/](mdc:frontend/src/components/forms/)** - Reusable form components with validation
68  - **Business Components:**
69    - **[components/admin/](mdc:frontend/src/components/admin/)** - Admin dashboard and management interfaces
70    - **[components/pos/](mdc:frontend/src/components/pos/)** - POS interface components (cart, product grid, etc.)
71    - **[components/kitchen/](mdc:frontend/src/components/kitchen/)** - Kitchen display system components
72    - **[components/server/](mdc:frontend/src/components/server/)** - Server-specific interface components
73    - **[components/counter/](mdc:frontend/src/components/counter/)** - Counter/checkout interface components
74  - **Routing:**
75    - **[routes/](mdc:frontend/src/routes/)** - TanStack Start file-based routing
76    - **[routeTree.gen.ts](mdc:frontend/src/routeTree.gen.ts)** - Auto-generated route tree
77  - **Hooks & State:**
78    - **[hooks/](mdc:frontend/src/hooks/)** - Custom React hooks (pagination, toasts, keyboard shortcuts)
79 
80### 🗄️ Database Structure (`database/`)
81- **[init/01_schema.sql](mdc:database/init/01_schema.sql)** - Complete PostgreSQL schema:
82  - Users with role-based access (admin, manager, server, counter, kitchen)
83  - Products and categories with inventory tracking
84  - Orders with full lifecycle management
85  - Dining tables with occupancy status
86  - Payments with multiple payment methods
87  - Order status history for audit trails
88  - Optimized indexes for performance
89- **[init/02_seed_data.sql](mdc:database/init/02_seed_data.sql)** - Demo data for all roles and complete workflows
90 
91### 🛠️ Scripts & Automation (`scripts/`)
92- **[create-admin.sh](mdc:scripts/create-admin.sh)** - Interactive super admin creation with validation
93- **[backup.sh](mdc:scripts/backup.sh)** - Production-grade system backup (database + files)
94- **[restore.sh](mdc:scripts/restore.sh)** - Interactive backup restoration with safety checks
95- **[db-reset.sh](mdc:scripts/db-reset.sh)** - Safe database reset with fresh schema and seed data
96- **[remove-data.sh](mdc:scripts/remove-data.sh)** - Destructive data removal with multiple confirmations
97 
98### 📚 Documentation (`docs/`)
99- **[PRD.md](mdc:docs/PRD.md)** - Complete Product Requirements Document with feature specifications
100- **[TODO.md](mdc:docs/TODO.md)** - Detailed project roadmap and development phases
101- **[README.md](mdc:README.md)** - Beautiful project documentation with screenshots and quick start
102 
103### ⚙️ Development Infrastructure
104- **[Makefile](mdc:Makefile)** - **ESSENTIAL** - All development operations (`make help` for full list)
105- **[.gitignore](mdc:.gitignore)** - Comprehensive ignore patterns for all environments
106- **Docker Configuration:**
107  - Development: [docker-compose.dev.yml](mdc:docker-compose.dev.yml) with hot reloading
108  - Production: [docker-compose.yml](mdc:docker-compose.yml) with optimized builds
109 
110## 🎯 Core Architectural Principles
111 
112### 1. 🚀 API-First Design
113- **RESTful APIs** - All business logic exposed through clean REST endpoints
114- **Client-Server Separation** - Frontend consumes APIs, backend serves data
115- **Consistent Response Format** - Standardized JSON responses with success/error patterns
116- **Versioned APIs** - `/api/v1/` prefix for future-proofing
117 
118### 2. 🔒 Type Safety & Data Integrity
119- **End-to-End TypeScript** - Frontend to backend interface consistency
120- **Database Constraints** - PostgreSQL constraints, foreign keys, check constraints
121- **Zod Validation** - Runtime validation for forms and API requests
122- **Strongly-Typed Models** - Matching data structures across all layers
123 
124### 3. 🛡️ Security-First Architecture
125- **JWT Authentication** - Stateless authentication with proper expiration
126- **Role-Based Access Control (RBAC)** - Granular permissions per user role
127- **SQL Injection Prevention** - Parameterized queries throughout
128- **CORS Configuration** - Proper cross-origin resource sharing
129- **Input Validation** - Multi-layer validation (frontend + backend + database)
130 
131### 4. ⚡ Performance & Scalability
132- **Database Optimization:**
133  - Strategic indexes on frequently queried columns
134  - Connection pooling for efficient resource usage
135  - Proper query optimization to prevent N+1 problems
136- **Frontend Optimization:**
137  - React.memo and useCallback for expensive components
138  - Code splitting and lazy loading
139  - Optimized bundle sizes with Vite
140- **Caching Strategy:**
141  - HTTP caching headers for static resources
142  - React Query for client-side caching
143 
144### 5. 👥 Role-Based Architecture
145- **Multi-Role Support:** Admin, Manager, Server, Counter, Kitchen
146- **Role-Specific Interfaces:** Tailored UX for each role's responsibilities
147- **Permission Boundaries:** API endpoints restricted by role
148- **Interface Switching:** Admin can access all role interfaces
149 
150### 6. 🔄 Real-Time Updates
151- **State Synchronization** - Orders sync across all connected interfaces
152- **Kitchen Display System** - Real-time order status updates
153- **Payment Flow** - Live payment status across POS interfaces
154 
155### 7. 🛠️ Developer Experience Excellence
156- **🎯 Primary Development Workflow:**
157```bash
158  make dev     # Start everything with hot reloading
159  make backup  # Create system backups before major changes
160  make status  # Check system health
161  make help    # See all available commands
162```
163- **🔐 Safety Features:**
164  - Interactive scripts with confirmation prompts
165  - Automatic emergency backups before destructive operations
166  - Comprehensive error messages with resolution suggestions
167- **🐳 Container-First Development:**
168  - Consistent environments across development/production
169  - Hot reloading in development containers
170  - Multi-stage production builds for optimization
171- **📊 Monitoring & Debugging:**
172  - Comprehensive logging with structured output
173  - Real-time log monitoring (`make logs`)
174  - Health check endpoints for all services
175 
176### 8. 🏗️ Clean Architecture Patterns
177- **Backend:** Standard Go project layout with internal packages
178- **Frontend:** Feature-based component organization
179- **Database:** Normalized schema with proper relationships
180- **Infrastructure:** Infrastructure as Code with Docker Compose
181 
182## 🚀 Quick Development Commands
183 
184Essential commands for daily development (all via Makefile):
185 
186```bash
187# 🏁 Getting Started
188make dev          # Start development environment
189make status       # Check system status
190make help         # Show all available commands
191 
192# 🗄️ Database Management
193make create-admin # Create admin user interactively
194make db-reset     # Reset to fresh database with seed data
195make backup       # Create complete system backup
196make restore      # Restore from backup (interactive)
197 
198# 📊 Monitoring & Debugging
199make logs         # View all service logs
200make logs-backend # View backend logs only
201make logs-frontend# View frontend logs only
202 
203# 🧹 Maintenance
204make down         # Stop all services
205make clean        # Clean up Docker resources (with confirmations)
206```
207 
208## 🎭 Demo Accounts for Testing
209 
210| Role | Username | Password | Access Level |
211|------|----------|----------|-------------|
212| **👑 Admin** | `admin` | `admin123` | Full system access + beautiful admin dashboard |
213| **🍽️ Server** | `server1` | `server123` | Dine-in orders only |
214| **💰 Counter** | `counter1` | `counter123` | All order types + payments |
215| **👨‍🍳 Kitchen** | `kitchen1` | `kitchen123` | Order preparation workflow |