This folder contains comprehensive documentation about everything happening in Intellidine. If you're new to the project or want to understand how systems work together, start here.
- SYSTEM_OVERVIEW.md - High-level architecture, data flow, and system interactions
- ARCHITECTURE_AT_A_GLANCE.md - One-page reference (tables, diagrams, patterns)
Each microservice has detailed documentation:
- API_GATEWAY.md - Request routing, rate limiting, authentication validation
- AUTH_SERVICE.md - Customer OTP, staff login, JWT tokens, session management
- MENU_SERVICE.md - Menu items, categories, pricing, dietary tags
- ORDER_SERVICE.md - Order creation, status tracking, order items
- PAYMENT_SERVICE.md - Razorpay integration, cash payments, payment status
- INVENTORY_SERVICE.md - Stock management, recipe ingredients, low stock alerts
- DISCOUNT_ENGINE.md - Dynamic pricing, ML integration, pricing rules
- NOTIFICATION_SERVICE.md - SMS alerts, order notifications, customer updates
- ANALYTICS_SERVICE.md - Metrics collection, reporting, dashboards
- ML_SERVICE.md - XGBoost discount prediction, model training
- DATABASE.md - Schema, relationships, indexes, migrations
- KAFKA_EVENTS.md - Event topics, consumers, event flow
- AUTHENTICATION.md - JWT tokens, OTP verification, staff login
- MULTI_TENANCY.md - Tenant isolation, data boundaries
- ORDERING_WORKFLOW.md - Complete order lifecycle from QR scan to completion
- PAYMENT_WORKFLOW.md - Payment processing, refunds, cash vs online
- DISCOUNT_APPLICATION.md - How ML discounts are calculated and applied
- INVENTORY_WORKFLOW.md - Stock updates, reservations, adjustments
- UML_DIAGRAMS.md - Comprehensive PlantUML diagrams (collaboration, sequence, class, database)
- ARCHITECTURE_DIAGRAMS_ASCII.md - Visual ASCII diagrams of system components, flows, and relationships
- diagrams/ - Rendered SVG diagrams:
IntelliDine_System_Collaboration.svg- System components & interactionsIntelliDine_Class_Diagram.svg- Database entities & relationships
- API_ENDPOINTS.md - All 35+ endpoints with examples
- ERROR_CODES.md - Error handling, status codes, troubleshooting
- GLOSSARY.md - Terms, acronyms, definitions
- Read SYSTEM_OVERVIEW.md (5 min)
- Read API_ENDPOINTS.md (10 min)
- Bookmark ORDERING_WORKFLOW.md
- Check individual service docs as needed
- Start with SYSTEM_OVERVIEW.md
- Read the relevant service docs for what you're working on
- Check DATABASE.md for schema
- Review KAFKA_EVENTS.md for event flows
- Read SYSTEM_OVERVIEW.md
- Check deployment setup in root README.md
- Review all service documentation for dependencies
- Monitor sections in each service doc
- Read SYSTEM_OVERVIEW.md
- Check ORDERING_WORKFLOW.md for customer journey
- Review GLOSSARY.md to understand terminology
- Check individual service docs for technical debt notes
What you'll learn:
- ✅ All 10 services and what they do
- ✅ How services talk to each other
- ✅ Data flow from customer order to kitchen display
- ✅ Multi-tenancy implementation
- ✅ Event-driven architecture with Kafka
- ✅ Authentication flows (OTP vs staff login)
- ✅ Database schema at high level
Each service file includes:
- What it does - Purpose and responsibilities
- Key endpoints - REST API with examples
- Data models - Prisma schema relevant to service
- Kafka events - What it publishes/consumes
- Dependencies - Other services it calls
- Error handling - Common issues and solutions
- Use cases - Real-world scenarios
- Testing - How to test the service
Each workflow file traces:
- Step-by-step - Exact sequence of operations
- Service interactions - Which services are involved
- Data transformations - How data changes through flow
- Event publishing - What Kafka events are emitted
- Error scenarios - What can go wrong and recovery
- Examples - Real customer scenarios with data
Intellidine is SaaS - many restaurants use the same system, completely isolated:
- Each restaurant has a
tenant_id(UUID) - All data filtered by
tenant_idat database level - Staff can only access their restaurant's data
- Customers only see their restaurant's menu
All services are stateless for scalability:
- No session data stored in services
- Everything stored in PostgreSQL + Redis
- Can run multiple instances behind load balancer
- Any instance can handle any request
Services communicate asynchronously via Kafka:
order.created→ triggers Notification, Analytics, Kitchenpayment.completed→ updates order statusinventory.low_stock→ alerts management
XGBoost model predicts optimal discounts:
- Real-time predictions based on current context
- Considers time of day, inventory, demand patterns
- Applied automatically to every order
- No extra API call visible to customer
| File | Size | Read Time |
|---|---|---|
| SYSTEM_OVERVIEW.md | ~3000 lines | 30 min |
| API_ENDPOINTS.md | ~2000 lines | 15 min |
| ORDERING_WORKFLOW.md | ~1500 lines | 20 min |
| Individual Service | ~500-800 lines | 10-15 min each |
| DATABASE.md | ~1000 lines | 15 min |
| KAFKA_EVENTS.md | ~800 lines | 10 min |
Total documentation: ~15,000 lines If you read everything: ~3-4 hours Recommended first reading: 1-2 hours (SYSTEM_OVERVIEW + your role-specific docs)
Intellidine is a restaurant ordering system with:
🍽️ For Customers:
- Scan QR code at table
- Browse menu via phone
- Add items to cart
- Place order (instantly sent to kitchen)
- Pay online or cash
👨💼 For Restaurant Staff:
- See orders on kitchen display
- Update order status (preparing → ready → served)
- Manage inventory & menu
- Process payments
- View analytics
🤖 For Backend:
- 10 microservices (each ~500-700 lines)
- PostgreSQL + Redis + Kafka
- Multi-tenant SaaS architecture
- JWT authentication
- ML-based discount prediction
📱 For Frontend:
- React app at port 3000
- Uses 35+ REST endpoints
- Real-time order updates
- Mobile-first design
"I need to add a new menu item field"
→ Check MENU_SERVICE.md for endpoints, then DATABASE.md for schema
"Why is my discount not being applied?"
→ Read DISCOUNT_APPLICATION.md workflow, check DISCOUNT_ENGINE.md service
"What happens when customer clicks 'Place Order'?"
→ Read ORDERING_WORKFLOW.md step-by-step with exact service calls
"How do I test the payment flow?"
→ Check PAYMENT_SERVICE.md for endpoints and PAYMENT_WORKFLOW.md for full flow
Bookmark these 3 while developing:
SYSTEM_OVERVIEW.md- Reference architectureAPI_ENDPOINTS.md- All endpoint signatures- Your service-specific file (e.g.,
ORDER_SERVICE.md)
Each service file has:
- Common Issues section with troubleshooting
- Examples with actual request/response JSON
- Related Files - links to other relevant documentation
If something isn't clear:
- Check the related service's README
- Look in GLOSSARY.md for term definitions
- Search workflow files for your use case
When updating code:
- Update the service's .md file
- Update KAFKA_EVENTS.md if events change
- Update DATABASE.md if schema changes
- Add new workflow files for major features
- Update this README with new file descriptions
Last Updated: October 22, 2025 System Version: 1.0 Frontend Integration Ready: ✅ YES
Happy documenting! 📚