Skip to content

FILE_INDEX.md

Latest commit

 

History

History
485 lines (407 loc) · 14.4 KB

FILE_INDEX.md

File metadata and controls

485 lines (407 loc) · 14.4 KB

📑 Complete File Index & Navigation Guide

🚀 Start Here

For First-Time Users

  1. PROJECT_SUMMARY.md ← Start here! High-level overview
  2. README.md - Project architecture and features
  3. SETUP_GUIDE.md - Step-by-step setup instructions

For Developers

  1. DEVELOPER_CHECKLIST.md - Quick reference guide
  2. IMPLEMENTATION_NOTES.md - Deep technical details
  3. Service-specific README files (coming soon)

📚 Documentation Files

Root Level

.env.example
└─ Template for environment variables
   • Database URLs for 3 PostgreSQL shards
   • MongoDB, Redis, RabbitMQ connections
   • Service ports and JWT settings
   • Shard region configuration

docker-compose.yml
└─ Complete multi-container orchestration
   • All 7 microservices + databases
   • PostgreSQL 3 shards (5432, 5433, 5434)
   • MongoDB, Redis, RabbitMQ services
   • Nginx load balancer
   • Network configuration
   • Volume persistence

nginx.conf
└─ Load balancer and reverse proxy configuration
   • Routing rules for all services
   • WebSocket upgrade for tracking
   • Rate limiting zones
   • Health check endpoint
   • CORS and security headers

tsconfig.base.json
└─ Base TypeScript configuration
   • ES2020 target
   • Strict mode enabled
   • Module resolution settings
   • Shared across all services

README.md
└─ Project overview (2,000+ lines)
   • Architecture diagram
   • Tech stack explanation
   • Database setup
   • API endpoint documentation
   • Getting started guide
   • Production considerations

SETUP_GUIDE.md
└─ Detailed setup instructions (2,000+ lines)
   • Complete folder structure
   • Service descriptions
   • Running the system (Docker & local)
   • Database setup
   • Event flow explanation
   • Monitoring & debugging

IMPLEMENTATION_NOTES.md
└─ Technical deep dive (3,000+ lines)
   • Sharding implementation details
   • Service architecture
   • Database schemas
   • Event flow diagrams
   • Performance considerations
   • Security recommendations
   • Scaling strategies
   • Deployment checklist

DEVELOPER_CHECKLIST.md
└─ Developer quick reference (1,500+ lines)
   • Getting started checklist
   • Adding new endpoints
   • Database operations
   • Event publishing/consuming
   • WebSocket usage
   • Authentication flows
   • Testing workflows
   • Debugging guide
   • Troubleshooting table

PROJECT_SUMMARY.md
└─ Executive summary (700+ lines)
   • What has been created
   • Tech stack overview
   • Quick start instructions
   • Service URLs
   • Key features
   • Next steps
   • Learning outcomes

start.sh
└─ Quick start script for Mac/Linux
   • Checks Docker installation
   • Creates .env files
   • Starts docker-compose
   • Shows service URLs

start.bat
└─ Quick start script for Windows
   • Same functionality as start.sh
   • Uses Windows batch syntax

🏗️ Project Structure

services/ - Microservices

api-gateway/

api-gateway/
├── src/
│   ├── index.ts                 # Express server + health check
│   ├── middleware/
│   │   ├── requestLogger.ts     # Request logging middleware
│   │   ├── errorHandler.ts      # Error handling middleware
│   │   └── rateLimit.ts         # Rate limiting middleware
│   ├── routes/
│   │   ├── auth.ts              # Auth service forwarding
│   │   ├── orders.ts            # Order service forwarding
│   │   ├── restaurants.ts       # Restaurant service forwarding
│   │   └── delivery.ts          # Delivery service forwarding
│   └── utils/
│       └── forwardRequest.ts    # HTTP forwarding utility
├── Dockerfile                   # Container image
├── package.json                 # Dependencies (Express, Axios)
└── tsconfig.json               # TypeScript config

Purpose: Central entry point, request routing, rate limiting
Port: 3000
Key Files: src/routes/* (route definitions)

auth-service/

auth-service/
├── src/
│   ├── index.ts                 # Express server + routes
│   ├── routes/
│   │   ├── register.ts          # User registration endpoint
│   │   ├── login.ts             # JWT login endpoint
│   │   └── refresh.ts           # Token refresh endpoint
│   └── services/
│       └── prismaService.ts     # Shard-aware Prisma client
├── prisma/
│   └── schema.prisma            # User table schema
├── Dockerfile
├── package.json                 # Dependencies (bcryptjs, jwt)
└── tsconfig.json

Purpose: Authentication, JWT, password hashing, role-based access
Port: 3001
Key Endpoints: /register, /login, /refresh
Database: PostgreSQL (sharded)

order-service/

order-service/
├── src/
│   ├── index.ts                 # Express server + order CRUD
│   └── services/
│       ├── rabbitmqService.ts   # Event publishing
│       └── prismaService.ts     # Shard-aware Prisma client
├── prisma/
│   └── schema.prisma            # Order, OrderItem schemas
├── Dockerfile
├── package.json                 # Dependencies (amqplib, Prisma)
└── tsconfig.json

Purpose: Order management, event publishing, sharded storage
Port: 3002
Key Endpoints: POST /, GET /:id, GET /, PATCH /:id/status
Events Published: order.created
Database: PostgreSQL (sharded by city)

restaurant-service/

restaurant-service/
├── src/
│   ├── index.ts                 # Express server + MongoDB connection
│   └── models/
│       ├── Restaurant.ts        # Mongoose Restaurant schema
│       └── MenuItem.ts          # Mongoose MenuItem schema
├── Dockerfile
├── package.json                 # Dependencies (mongoose)
└── tsconfig.json

Purpose: Restaurant metadata, menus (non-sharded)
Port: 3003
Key Endpoints: GET /, GET /:id, GET /:id/menu, POST /
Database: MongoDB
Models: Restaurant, MenuItem

delivery-service/

delivery-service/
├── src/
│   ├── index.ts                 # Express server + event consumer
│   └── services/
│       ├── rabbitmqService.ts   # Event consuming & auto-assignment
│       └── prismaService.ts     # Shard-aware Prisma client
├── prisma/
│   └── schema.prisma            # Order, DeliveryPartner schemas
├── Dockerfile
├── package.json                 # Dependencies (amqplib, Prisma)
└── tsconfig.json

Purpose: Delivery management, event consumption, auto-assignment
Port: 3004
Key Endpoints: GET /assignments, PATCH /:id/location, POST /:id/accept
Events Consumed: order.created, order.assigned
Database: PostgreSQL (sharded by city)

tracking-service/

tracking-service/
├── src/
│   ├── index.ts                 # Socket.IO server
│   └── services/
│       └── redisService.ts      # Redis operations
├── Dockerfile
├── package.json                 # Dependencies (socket.io, redis)
└── tsconfig.json

Purpose: Real-time order tracking, WebSocket server
Port: 3005
Key Socket Events: subscribe-order, location-updated, get-location
Database: Redis (ephemeral, 1-hour TTL)

frontend/

frontend/
├── src/
│   ├── main.tsx                 # React entry point
│   ├── App.tsx                  # Root component
│   ├── index.css                # Tailwind imports
│   ├── components/              # Reusable UI components
│   ├── pages/
│   │   ├── LoginPage.tsx        # Login form
│   │   ├── HomePage.tsx         # Main dashboard
│   │   └── TrackingPage.tsx     # Order tracking
│   ├── context/
│   │   └── AuthContext.tsx      # Auth state management
│   └── utils/
│       ├── apiClient.ts         # Axios instance
│       └── socketClient.ts      # Socket.IO client
├── index.html                   # HTML template
├── vite.config.ts              # Vite bundler config
├── tailwind.config.js          # Tailwind CSS config
├── postcss.config.js           # PostCSS config
├── tsconfig.json               # TypeScript config
├── tsconfig.node.json          # Node TypeScript config
├── package.json                # Dependencies (React, Vite, Tailwind)
└── .env.example                # Frontend env variables

Purpose: Web UI for customers & restaurants
Port: 5173
Tech: React 18, Vite, Tailwind CSS
Features: Authentication, order management, real-time tracking

shared/ - Shared Code

sharding/

shared/sharding/
├── shardConfig.ts              # Shard definitions
│   • ShardConfig interface
│   • shardConfigs object (3 shards)
│   • Region-to-shard mapping
│   • All shards array export
│
└── getShard.ts                 # Routing logic
    • getShardByRegion()        # Route by city
    • getShardById()            # Direct shard access
    • getAllShards()            # Get all configurations
    • determineUserShard()      # User routing
    • determineOrderShard()     # Order routing
    • getShardByHash()          # Consistent hashing

Regions Covered:
├─ Shard A: US-West, Canada
├─ Shard B: US-East, US-Central
└─ Shard C: US-South, Mexico

Usage: import { getShardByRegion } from 'shared/sharding/getShard'

events/

shared/events/
└── types.ts                    # Event type definitions
    ├── OrderEvents namespace
    │   ├── OrderCreatedEvent
    │   ├── OrderAssignedEvent
    │   ├── OrderStatusUpdatedEvent
    │   └── DeliveryLocationUpdatedEvent
    │
    └── RestaurantEvents namespace
        ├── RestaurantCreatedEvent
        └── RestaurantUpdatedEvent

Usage: import { OrderEvents } from 'shared/events/types'

types/

shared/types/
└── index.ts                    # Shared TypeScript interfaces
    ├── User interface          # User model
    ├── Order interface         # Order model
    ├── Restaurant interface    # Restaurant model
    ├── DeliveryPartner         # Delivery partner model
    ├── JWTPayload              # JWT token payload
    ├── ApiResponse<T>          # Standard API response
    └── PaginationParams        # Pagination helper

Usage: import { User, Order } from 'shared/types'

🔗 Cross-References

How Services Communicate

Frontend (React)
    ↓
Nginx (80) → Load Balancer
    ↓
API Gateway (3000)
    ├─→ Auth Service (3001)
    ├─→ Order Service (3002) ⟷ RabbitMQ ⟷ Delivery Service (3004)
    ├─→ Restaurant Service (3003)
    └─→ Delivery Service (3004)
    
Tracking Service (3005) ⟷ Frontend (WebSocket)

Database Connections

Auth Service ──┐
Order Service  ├─→ PostgreSQL Shard A (5432)
Delivery Svc   │

Auth Service ──┐
Order Service  ├─→ PostgreSQL Shard B (5433)
Delivery Svc   │

Auth Service ──┐
Order Service  ├─→ PostgreSQL Shard C (5434)
Delivery Svc   │

Restaurant Svc ─→ MongoDB (27017)

Tracking Svc ──→ Redis (6379)

Order Svc ─────┐
Delivery Svc ──┴─→ RabbitMQ (5672)

📊 File Type Distribution

Type Count Purpose
TypeScript 40+ Core application logic
JSON 12 Configuration & package files
Markdown 7 Documentation
Shell 2 Startup scripts
YAML 1 Docker Compose
Config 3 Nginx, Tailwind, PostCSS
Total 65+ Complete system

🎯 Navigation by Use Case

"I want to understand the architecture"

  1. READ: PROJECT_SUMMARY.md
  2. READ: README.md (Architecture section)
  3. READ: IMPLEMENTATION_NOTES.md (Architecture Highlights)

"I want to get this running locally"

  1. READ: README.md (Getting Started)
  2. RUN: ./start.sh or .\start.bat
  3. READ: SETUP_GUIDE.md (if issues)

"I want to add a new feature"

  1. READ: DEVELOPER_CHECKLIST.md (Adding new endpoint)
  2. EDIT: Appropriate service file
  3. UPDATE: API Gateway routes
  4. TEST: Using curl commands in DEVELOPER_CHECKLIST.md

"I want to understand database sharding"

  1. READ: shared/sharding/shardConfig.ts
  2. READ: shared/sharding/getShard.ts
  3. READ: IMPLEMENTATION_NOTES.md (Sharding Strategy section)

"I want to add a new microservice"

  1. READ: services/order-service/ (as template)
  2. COPY: Folder structure
  3. UPDATE: docker-compose.yml
  4. ADD: Routes to API Gateway
  5. READ: SETUP_GUIDE.md (Adding New Shards section)

"I want to understand event flow"

  1. READ: IMPLEMENTATION_NOTES.md (Event Flow)
  2. READ: services/order-service/src/index.ts
  3. READ: services/delivery-service/src/services/rabbitmqService.ts

"I want to debug an issue"

  1. READ: DEVELOPER_CHECKLIST.md (Debugging section)
  2. CHECK: docker-compose logs
  3. READ: DEVELOPER_CHECKLIST.md (Troubleshooting table)

"I want to deploy to production"

  1. READ: IMPLEMENTATION_NOTES.md (Production Considerations)
  2. UPDATE: .env with production values
  3. READ: IMPLEMENTATION_NOTES.md (Deployment Checklist)

📞 Key Files Quick Access

Need File Line
Database URLs .env.example 4-13
Shard Configuration shared/sharding/shardConfig.ts 1-20
Route Logic shared/sharding/getShard.ts 1-30
Order Service Events services/order-service/src/index.ts 20-70
Auth Endpoints services/auth-service/src/index.ts 1-30
Socket.IO Events services/tracking-service/src/index.ts 1-40
API Gateway Routes services/api-gateway/src/routes/ All files
Frontend Auth frontend/src/context/AuthContext.tsx 1-70
Docker Services docker-compose.yml 1-100

✅ Completion Status

  • API Gateway
  • Auth Service
  • Order Service
  • Restaurant Service
  • Delivery Service
  • Tracking Service
  • Frontend Scaffold
  • Shared Utilities
  • Docker Configuration
  • Documentation (8,000+ lines)
  • Startup Scripts
  • Environment Templates
  • TypeScript Configuration

🎉 Everything is complete and ready to use!

Start with PROJECT_SUMMARY.md or README.md → Run start.sh/start.bat → Read DEVELOPER_CHECKLIST.md for API examples.