🔗 SHORTRACE 🔗

ANALYTICS FRONTEND

🎯 Overview

ShortRace Analytics Frontend is the dashboard layer of the ShortRace ecosystem. Built with Svelte 5 + Vite + TypeScript, it visualizes click-tracking analytics for shortened links — rendering daily breakdowns and stat summaries in real time. Deployed on AWS as a fully static SPA served through CloudFront CDN with a private S3 backend. Every CI/CD step runs inside a Docker container to guarantee environment parity between local and GitHub Actions.

✨ Key Features

📊 Analytics Dashboard

• Real-Time Metrics: Queries the metrics microservice by link code and date range, displaying total clicks and day-by-day breakdowns.
• Chart.js Integration: Line chart powered by chart.js wrapped in a reusable LineChart.svelte component.
• Toast Notifications: Lightweight in-app feedback via a reactive Svelte store.

🐳 Docker-First CI

• Reproducible Environments: Every pipeline job (Lint, Check, Test, Deploy) builds and runs inside the same dockerfile.ci image — no environment drift between local and CI.
• Single Image, All Jobs: node:22-alpine with aws-cli baked in covers type checks, test runs, and S3 deployments from the same base.

☁️ Cloud-Native Deployment

• CDN-First: Served through Amazon CloudFront with HTTPS enforced — no plain HTTP.
• Private S3 Origin: Bucket is fully private; CloudFront reads assets via Origin Access Control (OAC) — no public bucket policies.
• SPA Routing: CloudFront custom error responses redirect all 403/404s back to index.html for client-side routing.

🏗️ Automated CI/CD

• Branch-Aware Pipeline: GitHub Actions runs Lint on every push, adds TypeScript Check and Test coverage on develop, and executes the full Deploy chain on main.
• Zero-Downtime Deploys: aws s3 sync --delete replaces only changed files, followed by an automatic CloudFront cache invalidation.

🏗️ Project Structure

.
├── .github/
│   ├── docker/
│   │   └── dockerfile.ci          # CI Docker image (node:22-alpine + aws-cli)
│   ├── events/
│   │   ├── push-develop.json      # act event payload for develop branch
│   │   └── push-main.json         # act event payload for main branch
│   └── workflows/
│       └── ci-cd.yml              # GitHub Actions pipeline
├── terraform/
│   ├── provider.tf                # AWS provider & Terraform version
│   ├── variables.tf               # Input variables
│   ├── s3.tf                      # Private S3 bucket + OAC bucket policy
│   ├── cloudfront.tf              # CloudFront distribution + OAC
│   └── outputs.tf                 # Bucket name, distribution ID, public URL
└── src/
    ├── core/
    │   ├── api/                   # Axios HTTP client
    │   ├── models/                # Domain models (Metric, DateRange)
    │   ├── services/              # Metrics service (business logic)
    │   └── stores/                # Svelte reactive stores (Toast)
    └── lib/
        ├── components/            # Reusable UI components (StatCard, LineChart, Toast)
        └── features/              # Page-level feature components (Dashboard)

📱 Screenshots

Metrics Page

🚀 Getting Started

Prerequisites

• Node.js 22+
• Docker — required to run the CI image locally.
• act — to simulate GitHub Actions locally (nektos/act).
• AWS CLI configured with appropriate permissions.
• Terraform v1.5.0+ for infrastructure provisioning.

🛠️ Local Development

1. Clone the repository

   git clone https://github.com/MaySalguedo/SHORTRACE-ANALYTICS-FRONTEND.git
   cd SHORTRACE-ANALYTICS-FRONTEND
   npm install
   

2. Start the dev server

   npm run dev
   

3. Run the full quality gate before pushing

   # svelte-check + tsc + eslint + vitest coverage — all in sequence
   npm run validate
   

☁️ Infrastructure Provisioning

1. Provision AWS resources for the first time

   # Initializes Terraform state and applies the full infrastructure
   npm run compile:init
   

2. Update infrastructure after changes

   npm run compile
   

3. Preview changes without applying

   npm run tf:plan
   

4. Tear down all resources

   npm run tf:destroy
   

🚀 Manual Deploy (without CI/CD)

Export the required environment variables and run:

export S3_BUCKET_NAME=your-bucket-name
export CLOUDFRONT_DISTRIBUTION_ID=your-distribution-id

# Build, sync to S3 and invalidate CloudFront in one command
npm run deploy

You can retrieve both values after provisioning with npm run tf:output.

🛠️ Tech Stack

1. Framework: Svelte 5 with TypeScript for reactive, type-safe UI development.
2. Bundler: Vite 8 — instant HMR in dev, optimized static output for production.
3. Testing: Vitest + Testing Library with V8 coverage reporting.
4. Linting: ESLint + typescript-eslint + eslint-plugin-svelte.
5. Styling: Tailwind CSS v4 with PostCSS.
6. Task Runner: npm-run-all (run-s) for sequential script chaining.
7. CI Runtime: Docker (node:22-alpine + aws-cli) — same image locally and in GitHub Actions.
8. CDN: Amazon CloudFront with Origin Access Control (OAC).
9. Storage: Amazon S3 — private bucket, no public access.
10. IaC: Terraform for full infrastructure provisioning.
11. CI/CD: GitHub Actions with a branch-conditional, Docker-powered pipeline.

⚙️ CI/CD Pipeline

The pipeline runs automatically on every push. All jobs build and run the same Docker image (dockerfile.ci) — guaranteeing identical behaviour between your machine and GitHub's runners.

Branch behavior

All branches:   Lint
develop:        Lint → Check (ts) → Test
main:           Lint → Test → Deploy

Deploy job steps

1. Builds the CI Docker image from .github/docker/dockerfile.ci.
2. Runs npm run deploy inside the container, which chains:
   • build → deploy:s3 → deploy:invalidate
3. AWS credentials and environment variables are injected at runtime via -e flags — never baked into the image.

🔐 Required GitHub Secrets & Variables

Navigate to Settings → Secrets and variables → Actions in your repository and add:

Secrets

Variables (non-sensitive, visible in logs)

💡 Run npm run tf:output after provisioning to get SHORTRACE_S3_BUCKET_NAME and SHORTRACE_CLOUDFRONT_DISTRIBUTION_ID.

🐳 Testing the Pipeline Locally

The pipeline can be tested locally with Docker and act before pushing. Event payloads are pre-configured in .github/events/.

Build the CI image manually

docker build -t shortrace-ci -f .github/docker/dockerfile.ci .

Run individual jobs with Docker

# Lint
docker run --rm shortrace-ci npm run lint

# Type check
docker run --rm shortrace-ci npm run check

# Tests with coverage
docker run --rm shortrace-ci npm run test:cov

Simulate the full pipeline with act

Create a .secrets and .vars on the root directory to store the secrets and variables.

Install act following the official guide, then:

# Simulate a push to develop (runs Lint → Check → Test)
act push -e .github/events/push-develop.json

# Simulate a push to main (runs Lint → Check → Test → Deploy)
act push -e .github/events/push-main.json --secret-file .secrets --var-file .vars

act uses the same ubuntu-latest runner image by default. Since jobs build dockerfile.ci themselves, Docker must be running on your machine.

Event payload reference

The .github/events/ folder contains minimal push payloads that tell act which branch to simulate:

// push-develop.json
{ "ref": "refs/heads/develop" }

// push-main.json
{ "ref": "refs/heads/main" }

📡 npm Scripts Reference

📦 Terraform Outputs

After running npm run compile:init or npm run tf:output, Terraform prints: