NovaBuy Complete 5-Year Project Blueprint

What it is: The single HTML shell — the "picture frame" of the entire application.

What it does: Defines the page structure: <header id="header-root"> (navigation bar), <main id="app-root"> (where pages render), <aside id="cart-sidebar"> (sliding cart drawer), <div id="login-modal"> (login popup), and <div id="toast-container"> (notification popups). Imports Google Fonts (Inter, Outfit), Lucide icons CDN, styles.css, and all JavaScript files in dependency order.

How it connects: Loaded by the browser from CloudFront/S3. Mounts app.js which orchestrates all component rendering.

What it is: The complete CSS design system — 41KB of styling rules implementing a premium dark-mode e-commerce theme.

What it does: Defines CSS custom properties (variables) for the entire color palette (--bg, --text, --accent), typography, spacing, and radii. Implements glassmorphism effects (backdrop-filter: blur(12px)), CSS Grid product catalogs, flexbox layouts, keyframe animations (slideIn, fadeIn), skeleton loaders, responsive breakpoints for mobile/tablet/desktop, and styles for every component: product cards, cart sidebar, checkout form, order cards, buttons, toasts, modals, hero section.

How it connects: Linked in index.html. Every JavaScript component generates HTML markup using CSS class names defined here.

What it is: The centralized messenger between the frontend and backend. Every single HTTP request goes through this file.

What it does:

• Base URL detection: If running on localhost, connects to http://localhost:8080. On CloudFront, reads the configured Elastic Beanstalk URL
• Token management: Stores/retrieves JWT tokens from localStorage. Automatically attaches Authorization: Bearer <token> to every request
• Auto-logout: If the server returns HTTP 401 (token expired), automatically clears the token and refreshes the UI
• Public methods: login(), logout(), getProducts(), getCategories(), addToCart(), getCart(), updateCartItem(), removeCartItem(), createOrder(), getOrders()

How it connects: Every frontend component calls methods on the API object. The API object talks to the backend via HTTP fetch().

What it is: The traffic cop that decides which page content to show based on the URL hash.

What it does: Listens for hashchange events. When the URL changes from #/ to #/products, it matches against route patterns and calls the corresponding component's render function.

What it does: The largest frontend component. Renders the home page hero section, product grid with cards, debounced search input, category filter pills, price/name sorting, and individual product detail pages with quantity pickers and stock indicators. Calls API.getProducts() and API.addToCart().

What it does: The sliding cart sidebar drawer. Shows cart items with product images, quantities, subtotals, and a checkout button. Supports real-time quantity adjustment and item removal. Updates the header cart badge count via custom cart-change events.

What it does: Renders the checkout page with an order summary and a shipping form (name, address, city, state, ZIP). Validates required fields and ZIP format. Calls API.createOrder(shippingData) to place the order, then redirects to #/orders.

What it does: Displays the user's complete order history. Each order card shows order number, date, status badge, shipping address, line items with frozen purchase prices, and grand total.

login.js (2,727 bytes): Modal dialog for user login. Calls API.login(username, password). On success, dispatches an auth-change custom event so header and cart can react.

header.js (2,100 bytes): Navigation bar with logo, nav links, cart icon with badge, and login/logout buttons. Listens for auth-change and cart-change events to update UI state.

What it provides:

• formatPrice(29.99) → "$29.99" — Formats numbers as USD currency
• formatDate("2024-09-15T10:30:00Z") → "Sep 15, 2024" — Formats ISO dates
• debounce(fn, 300) — Prevents a function from firing too often (used for search)
• showToast("Item added!", "success") — Shows a pop-up notification
• escapeHtml(str) — Prevents XSS attacks by escaping HTML special characters in user input before DOM insertion
• getProductImageSVG("Electronics") — Generates SVG placeholder images

What it does, step by step:

1. Loads environment variables from .env via require('dotenv').config()
2. Creates Express application: const app = express()
3. Adds Helmet.js: sets 11+ HTTP security headers (X-XSS-Protection, X-Content-Type-Options, etc.)
4. Configures CORS: in local mode allows all origins (*), in production only allows the CloudFront URL
5. Adds body parsing: express.json({ limit: '1mb' })
6. Registers health check endpoint GET /api/health — used by Elastic Beanstalk to verify the Docker container is alive
7. Mounts 4 route modules: /api/auth, /api/products, /api/cart, /api/orders
8. 404 handler for undefined API routes
9. Global error handler: catches all unhandled errors, returns JSON error (hides stack traces in production)
10. startServer(): connects to database, syncs schema (force: true in local, alter: false in prod), auto-seeds in local mode, starts listening on port 8080

The single most important architectural decision in the project.

database.js — Core Logic
// If ENV=production → Connect to PostgreSQL (Aurora on AWS)
// If ENV=local (default) → Use SQLite in-memory (no setup needed)

if (env === 'production') {
  // PostgreSQL with host, port, user, password from env vars
  // Pool: max 5 connections, SSL required for Aurora
  return new Sequelize(DB_NAME, DB_USER, DB_PASSWORD, {
    host, port, dialect: 'postgres',
    pool: { max: 5, min: 1, acquire: 30000, idle: 10000 },
    dialectOptions: { ssl: { require: true, rejectUnauthorized: false } }
  });
} else {
  // SQLite — zero config, data lives in RAM
  return new Sequelize({ dialect: 'sqlite', storage: ':memory:' });
}

How it works:

1. Checks if the request has an Authorization header starting with Bearer
2. Extracts the token string after "Bearer "
3. Calls jwt.verify(token, JWT_SECRET) to decode and verify the cryptographic signature
4. If valid: attaches { userId, username, role } to req.user and calls next()
5. If expired: returns 401 "Token expired"
6. If invalid: returns 401 "Invalid token"

Used by: routes/cart.js and routes/orders.js — both start with router.use(authenticate), meaning ALL routes in those files require a valid JWT.

POST /api/auth/login — Accepts { username, password }. Finds user by username, verifies password with bcrypt, generates JWT with 24-hour expiry, returns token + user info. Returns the same "Invalid credentials" error for both wrong username AND wrong password (prevents user enumeration attacks).

• GET /api/products — Lists products. Supports ?category=Electronics&search=keyboard&featured=true&sort=price_asc
• GET /api/products/categories — Distinct category names for filter dropdown
• GET /api/products/:id — Single product by UUID

• GET /api/cart — Current user's cart with items, product details, totals
• POST /api/cart/items — Add product. Upserts if already in cart. Checks stock.
• PUT /api/cart/items/:id — Update quantity. Validates stock.
• DELETE /api/cart/items/:id — Remove single item
• DELETE /api/cart — Clear entire cart

POST /api/orders — The checkout process. Executes inside a sequelize.transaction(): validates cart items → checks stock → creates Order record → creates OrderItem records with frozen prices → decrements Product.stock → clears CartItems → commits transaction. If any step fails, everything rolls back.

• GET /api/orders — Lists all user's orders, newest first
• GET /api/orders/:id — Single order (users can only see their own)

Stage 1 (deps): Uses node:20-alpine. Copies package.json first (Docker layer caching). Installs build tools (python3 make g++) for native sqlite3 compilation. Runs npm ci --omit=dev. Removes build tools.

Stage 2 (final): Fresh node:20-alpine. Creates non-root user appuser (UID 1001). Copies only node_modules from Stage 1 (not build tools). Copies src/. Switches to USER appuser. Exposes 8080. Defines HEALTHCHECK (wget -qO- http://localhost:8080/api/health every 30s). CMD ["node", "src/server.js"].

Result: ~80MB image (vs ~1.1GB for default Node.js). Uses node directly instead of npm start to avoid extra process layer.

Problem: Terraform needs to remember what it has created ("state"). If you lose this, Terraform doesn't know what exists in AWS.

Creates:

• S3 Bucket — Stores terraform.tfstate files. Versioning enabled (recover from corruption). AES-256 encryption (protect sensitive data). All 4 public access settings blocked.
• DynamoDB Table — State locking. When someone runs terraform apply, a lock is placed. If someone else tries simultaneously, they get blocked. Prevents concurrent corruption.

Chicken-and-egg: This project uses LOCAL state because you can't store state in an S3 bucket that doesn't exist yet. Once created, all other modules use it.

Creates (in order):

1. VPC — Isolated network 10.0.0.0/16 (65,536 IPs). DNS hostnames enabled.
2. 2 Public Subnets — 10.0.1.0/24 and 10.0.2.0/24 in different AZs (Aurora requires multi-AZ)
3. Internet Gateway + Route Table — Allows VPC resources to reach the internet
4. Security Group for Aurora — Only allows port 5432 from within VPC CIDR. No internet access.
5. DB Subnet Group — Tells Aurora which subnets to use
6. Random Password — 32-character password generated at plan time. Never in source code.
7. Aurora Serverless v2 Cluster — PostgreSQL 15.4 engine, 0.5–1.0 ACU scaling, encrypted storage, 1-day backup, skip_final_snapshot=true, deletion_protection=false
8. Aurora Instance — db.serverless instance class. NOT publicly accessible.
9. Secrets Manager (DB) — Stores username, password, host, port, dbname as JSON
10. Secrets Manager (App) — Stores JWT secret (64 random chars) and admin password

variables.tf: aws_region, project_name, vpc_cidr, db_name, db_master_username, aurora_min_capacity (0.5), aurora_max_capacity (1.0)

outputs.tf: Exports vpc_id, subnet_ids, aurora_endpoint, aurora_port, security_group_id, db_credentials_secret_arn, app_credentials_secret_arn, db_name — consumed by module 02.

Reads: Remote state from 01-database via data "terraform_remote_state" "database"

Creates:

1. IAM Service Role — Used by EB itself. Has AWSElasticBeanstalkEnhancedHealth and AWSElasticBeanstalkService policies.
2. IAM EC2 Role + Instance Profile — The role assumed by the EC2 running Docker. Has a custom least-privilege policy allowing secretsmanager:GetSecretValue ONLY on the 2 specific secret ARNs. No wildcard *.
3. Security Group for EC2 — Allows HTTP (port 80) from anywhere + all outbound
4. EB Application — Keeps only 5 most recent deployment versions
5. EB Environment — Single-instance mode (no ALB = $16/mo savings). t3.micro. Placed in VPC. Environment variables injected: ENV=production, PORT=8080, DB_HOST, DB_PORT, DB_NAME, secret ARNs. Health check: /api/health. CloudWatch logging with 7-day retention.

Creates:

1. S3 Bucket — Frontend static files. Versioning enabled. ALL 4 public access settings blocked.
2. CloudFront OAC — Modern Origin Access Control with SigV4 signing. Only CloudFront can read from S3.
3. CloudFront Distribution — PriceClass_100 (NA+EU edges). HTTP→HTTPS redirect. Gzip+Brotli compression. Custom error responses (403/404 → index.html for SPA routing).
4. S3 Bucket Policy — Only allows s3:GetObject from the specific CloudFront distribution ARN.

Deploys the entire stack in dependency order:

1. Step 1/4: terraform apply on 01-database → Creates VPC, Aurora, Secrets
2. Step 2/4: terraform apply on 02-backend → Creates IAM, Elastic Beanstalk
3. Step 3/4: Builds Docker image, packages deployment ZIP, deploys to EB
4. Step 4/4: terraform apply on 03-frontend → Creates S3+CloudFront, then aws s3 sync uploads frontend, then aws cloudfront create-invalidation clears CDN cache

Destroys everything in REVERSE order: empty S3 → destroy 03-frontend → destroy 02-backend → destroy 01-database. Includes confirmation prompt. Result: $0/month.

.gitignore: Prevents node_modules, .env, *.tfstate, .terraform/, .DS_Store from entering Git. .dockerignore: Prevents node_modules, .env, docs from entering Docker build context. docker-compose.yml: Orchestrates db (postgres:15-alpine with health check) and api (built from Dockerfile) with private networking and pgdata volume. .env: Local secrets (never committed). .env.example: Committed template with placeholder values.