Documentation

Technical documentation, API references, and implementation guides

Complete Technical Documentation

Download comprehensive documentation including detailed code examples, API specifications, database schemas, and deployment guides.

Installation & Setup Guide Technical Code Documentation
Complete

Technical Documentation

Complete developer guide and technical reference for the PizzaWorld Dashboard system.

System Architecture

PizzaWorld is a full-stack business intelligence dashboard with microservices architecture:

  • Backend: Spring Boot REST API with 90+ endpoints
  • Frontend: Angular SPA with TypeScript
  • AI Layer: Google Gemma integration with knowledge base
  • Security: JWT authentication with role-based access
  • Database: Supabase PostgreSQL with 15+ materialized views
  • Analytics: Advanced store, customer, and product analytics
  • Export System: Comprehensive CSV export for all data views
  • Email Support: Background email processing system

System Requirements

  • Java: Java 17 or higher (OpenJDK or Oracle JDK)
  • Node.js: Node.js 18 or higher with npm 9+
  • Browser: Modern web browser (Chrome, Firefox, Safari, Edge)
  • Operating System: Windows 10+, macOS 10.15+, or Linux
  • Database: No PostgreSQL installation required (uses Supabase cloud)
  • Memory: Minimum 4GB RAM recommended for development
🔒 Security Note

Always use the provided start scripts (start.bat / start.sh). Direct execution will fail due to missing environment variables for security.

Technology Stack

Backend Framework: Spring Boot 3.4.6
Security: Spring Security 6.x
Database: PostgreSQL (Supabase)
Frontend Framework: Angular 19
Language: TypeScript 5.7
UI Library: PrimeNG + Tailwind
Charts: ApexCharts 3.41
AI Integration: Google Gemma

API Reference

Backend Package Structure

src/main/java/pizzaworld/
├── controller/          # REST API Controllers
│   ├── AuthController.java
│   ├── OptimizedPizzaController.java
│   ├── AIController.java
│   └── SupportController.java
├── service/            # Business Logic Layer
│   ├── OptimizedPizzaService.java
│   ├── AIService.java
│   ├── GemmaAIService.java
│   └── EmailService.java
├── repository/         # Data Access Layer
│   ├── OptimizedPizzaRepo.java
│   └── UserRepo.java
├── model/             # Entity Classes
│   ├── User.java
│   ├── ChatMessage.java
│   └── AIInsight.java
├── security/          # Security Components
│   ├── JwtAuthFilter.java
│   └── SecurityConfig.java
└── config/           # Configuration Classes
    ├── CorsConfig.java
    └── EmailConfig.java

Core API Endpoints

Authentication
POST /api/login User authentication with JWT token generation
GET /api/me Current user information and permissions
Dashboard & Analytics
GET /api/v2/dashboard/kpis Main KPI metrics with role-based filtering
GET /api/v2/orders/recent Recent orders with pagination support
GET /api/v2/analytics/revenue/by-year Annual revenue trends and forecasting
GET /api/v2/analytics/customer-lifetime-value Customer segmentation and CLV analysis
Store Analytics
GET /api/v2/stores Store directory with role-based filtering
GET /api/v2/stores/performance Store performance analytics with benchmarking
GET /api/v2/stores/{storeId}/analytics/overview Individual store comprehensive analytics
Product Analytics
GET /api/v2/products Product catalog with advanced filtering
GET /api/v2/products/performance Product performance analytics and trends
GET /api/v2/products/kpi Product KPIs with comparative analysis
Customer Analytics
GET /api/v2/analytics/customer-lifetime-value Customer segmentation and CLV analysis
GET /api/v2/analytics/customer-retention Customer retention analysis and cohort tracking
GET /api/v2/analytics/store-capacity-v3/metrics Advanced store capacity and utilization metrics
AI Assistant
POST /api/ai/chat AI chat interaction with business context
POST /api/ai/chat/stream Real-time streaming AI responses (SSE)
GET /api/ai/insights AI-generated business insights and recommendations
Data Export
GET /api/v2/dashboard/kpis/export Export dashboard KPIs to CSV
GET /api/v2/orders/export Export filtered orders with role-based access
GET /api/v2/stores/performance/export Export store performance analytics

Security & Authentication

Security Implementation

  • JWT Authentication: Stateless token-based authentication with 24-hour expiration
  • Role-based Access Control: HQ_ADMIN, STATE_MANAGER, STORE_MANAGER permissions
  • BCrypt Password Hashing: Secure credential storage with salt rounds
  • Spring Security 6: Comprehensive security framework with CSRF protection
  • CORS Configuration: Cross-origin resource sharing for frontend integration
  • Environment Variables: No hardcoded credentials in source code

Authentication Flow

  1. User submits credentials to /api/login endpoint
  2. Server validates credentials against BCrypt hash in database
  3. JWT token generated with user role and permissions embedded
  4. Token returned to client with 24-hour expiration time
  5. Client includes token in Authorization header for subsequent requests
  6. JwtAuthFilter validates token signature and expiration on each request
  7. Security context set with user details and role-based permissions

Role-Based Permissions

HQ_ADMIN: Full system access, all stores and states
STATE_MANAGER: State-level access, multiple stores within assigned state
STORE_MANAGER: Store-specific access, single store operations

Database Architecture

Database Optimization

  • Materialized Views: 15+ pre-computed views for sub-100ms response times
  • Role-based Data Access: Automatic filtering by user permissions
  • Connection Pooling: HikariCP with 30 max connections and optimized timeouts
  • Query Optimization: Native SQL with strategic indexing
  • Supabase Integration: Cloud PostgreSQL with SSL/TLS encryption
  • Performance Monitoring: Query execution time tracking and optimization

Key Materialized Views

kpis_global_hq: Company-wide KPI metrics
kpis_global_state: State-level performance data
kpis_global_store: Individual store analytics
revenue_by_year_hq: Annual revenue trends
customer_lifetime_value: CLV analysis and segmentation
store_performance_hq: Store ranking and benchmarking

Deployment & Performance

Performance Achievements

Sub-100ms Query Response Time
100+ Store Locations Supported
99.9% Data Accuracy
30 Max DB Connections

Deployment Configuration

  • Docker Containerization: Eclipse Temurin JDK 17 with optimized layers
  • JVM Optimization: G1GC with 2GB heap allocation and performance tuning
  • Cloud Deployment: Render.com with auto-scaling and load balancing
  • Environment Management: Secure configuration with encrypted environment variables
  • CI/CD Pipeline: Automated build, test, and deployment workflow
  • Monitoring: Application performance monitoring and error tracking

Demo Data & Testing

Comprehensive Demo Dataset

The application includes extensive demo data for testing and demonstration purposes:

4 US States Arizona, California, Nevada, Utah
52 Store Locations Distributed across all states
100,000+ Historical Orders 3 years of data (2021-2023)
25+ Product Types Various pizza types and sizes
  • Realistic Business Scenarios: Authentic order patterns and seasonal variations
  • Performance Metrics: Pre-calculated analytics for immediate testing
  • Role-Based Data: Different data access levels for each user role
  • Historical Trends: Multi-year data for trend analysis and forecasting
  • Geographic Distribution: Store performance across multiple states

AI Integration & Features

Google Gemma AI Capabilities

  • Real-time Streaming: Server-Sent Events for token-by-token response delivery
  • Business Context Integration: AI responses include live business data and metrics
  • Role-based Responses: Tailored answers based on user permissions and access level
  • Knowledge Base Integration: Contextual responses using business documentation
  • Non-persistent Sessions: Conversation history limited to last 20 messages
  • Intelligent Fallbacks: Rule-based responses when AI service unavailable

Frontend Architecture

Angular 19: Latest framework with standalone components
TypeScript 5.7: Type-safe development with strict mode
RxJS: Reactive programming with observables and operators
PrimeNG + Tailwind: Component library with utility-first CSS
ApexCharts: Interactive data visualization and charting
PWA: Progressive Web App with offline capabilities

Platform Demonstration

Complete PizzaWorld+ Demo

Watch our comprehensive demonstration showcasing all platform features, real-time analytics, dashboard functionality, and business intelligence capabilities.

Technical Demonstrations

Email Service Demo

Watch our live demonstration of the email service functionality, showing SMTP integration, automated notifications, and support ticket management in action.

Complete Technical Documentation

Download comprehensive documentation including detailed code examples, API specifications, database schemas, and deployment guides.

Installation & Setup Guide Technical Code Documentation

Quick Links

GitHub Repository View source code and contribute
Live Dashboard Access the live platform
Development Blog Latest updates and insights
Technical Support Get help with implementation