init

Author: Jay Gandhi

.gitignore

@@ -0,0 +1,22 @@
+**/node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+**/__pycache__
+**/dist/
+**/build/
+
+.DS_Store
+.npm
+
+# IDE
+.idea/
+*.swp
+*.swo
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local

README.md

@@ -0,0 +1,106 @@
+# Carbon Emissions Benchmarking Exercise
+
+## Overview
+
+This is a fullstack development exercise for building a carbon emissions benchmarking dashboard for digital advertising. You'll work with real data from Scope3's carbon emissions API to create a system that helps advertisers understand and compare environmental impact across different properties.
+
+## Project Setup
+
+1. ** Use `nvm` to enable the correct Node.js version for the project:
+   ```bash
+   nvm use
+   ```
+
+2. Run `npm install` in the root directory to install dependencies for both the backend and frontend.
+
+### Getting Started
+
+1. **Setup Environment Variables**:
+   ```bash
+   cd backend
+   cp .env.example .env
+   # Edit .env and add your API token (provided by interviewer)
+   ```
+
+2. **Start the Backend**:
+   ```bash
+   npm run backend:start
+   ```
+
+3. **Start the Frontend**:
+   ```bash
+   npm run frontend:start
+   ```
+
+### Project Structure
+
+```
+├── backend/          # TypeScript Express server
+│   ├── app.ts       # Main server file with /forward endpoint
+│   ├── tests/       # Jest test files
+│   ├── .env.example # Environment variables template
+│   ├── jest.config.js
+│   └── package.json
+├── frontend/         # React TypeScript application
+│   ├── src/
+│   │   ├── types.ts     # TypeScript type definitions
+│   │   ├── api.ts       # API service functions
+│   │   ├── constants.ts # Available channels and countries
+│   │   └── App.tsx      # Main application component
+│   └── package.json
+├── .gitignore        # Git ignore rules
+└── README.md
+```
+
+## Understanding the Data
+
+The backend provides a `/forward` endpoint that proxies requests to Scope3's API:
+
+```bash
+# Example API calls:
+POST /forward
+{ "channel": "web", "country": "US" }
+
+POST /forward
+{ "channel": "app", "country": "GB" }
+```
+
+**Available Options:**
+- **Channels**: `web`, `app`
+- **Countries**: See `frontend/src/constants.ts` for the full list
+
+The API returns carbon emissions benchmarks measured as emissions per thousand impressions, organized by percentiles.
+
+## What You'll Be Building
+
+The frontend includes a starter DataGrid displaying sample property data (Property Name, Channel, Country, CO2 values) to give you a visual starting point.
+
+Your interviewer will provide specific tasks, but generally you'll be creating a dashboard that allows advertisers to:
+- View carbon emissions data for different advertising properties
+- Compare emissions across channels and countries
+- Organize and analyze collections of properties
+
+## Resources Available
+
+- **TypeScript Types**: Starter types in `frontend/src/types.ts`
+- **API Service**: Basic fetch function in `frontend/src/api.ts`
+- **Constants**: Predefined channels and countries in `frontend/src/constants.ts`
+- **Backend Testing**: Jest setup with sample tests in `backend/tests/` (run with `npm test`)
+- **Scope3 API Docs**: Find our documentation of the `/v2/measure` api [here](https://docs.scope3.com/reference/measure-1)
+
+### Available UI Libraries
+
+- **Material-UI Core**: Buttons, Cards, Typography, Forms, etc.
+- **MUI Data Grid**: Professional data tables with sorting, filtering, and selection
+- **MUI X Charts**: Bar charts, line charts, pie charts for data visualization
+- **MUI Icons**: Comprehensive icon library for UI elements
+
+## Approach
+
+- Take your time to understand the requirements and ask questions
+- Build incrementally - get each piece working before moving to the next
+- Focus on functionality over styling - Material-UI is provided for easy UI development
+- Consider user experience and real-world usage
+- Don't hesitate to ask for clarification on any requirements
+
+Your interviewer will guide you through the specific features to implement. The goal is to demonstrate your fullstack development skills, API design thinking, and ability to build user-focused interfaces.

backend/.env.example

@@ -0,0 +1,9 @@
+# Environment variables for the backend server
+# Copy this file to .env and fill in your actual values
+
+# Scope3 API Token - get this from your interviewer
+SCOPE3_API_TOKEN=your_scope3_api_token_here
+
+# Server configuration
+PORT=4000
+NODE_ENV=development

backend/app.ts

@@ -0,0 +1,117 @@
+import express from 'express'
+import type { Request, Response } from 'express'
+import axios from 'axios'
+import type { AxiosResponse, AxiosError } from 'axios'
+import cors from 'cors'
+import dotenv from 'dotenv'
+
+// Load environment variables
+dotenv.config()
+
+const app = express()
+const PORT = process.env.PORT || 4000
+
+// Middleware to parse JSON bodies
+app.use(express.json())
+
+// Enable CORS for localhost:3000
+app.use(
+  cors({
+    origin: 'http://localhost:3000',
+  })
+)
+
+// Get API token from environment variables
+const token = process.env.SCOPE3_API_TOKEN
+
+if (!token) {
+  console.error('SCOPE3_API_TOKEN environment variable is required')
+  console.error('Copy .env.example to .env and add your API token')
+  console.error('Contact your interviewer to get the API token')
+  process.exit(1)
+}
+
+// Interface for the basic benchmark request
+interface BenchmarkRequest {
+  channel?: string
+  country?: string
+  ymd?: string
+  [key: string]: any // Allow additional properties
+}
+
+// Helper function to map frontend channels to API parameters
+function mapChannelToApiParams(channel: string): { [key: string]: any } {
+  switch (channel) {
+    case 'web':
+      return { device: 'desktop' }
+    case 'app':
+      return { device: 'mobile' }
+    default:
+      return { device: 'desktop' } // Default fallback
+  }
+}
+
+// POST /forward - Forward requests to Scope3 API
+app.post(
+  '/forward',
+  async (req: Request<{}, any, BenchmarkRequest>, res: Response) => {
+    try {
+      // Transform the request body to use the proper API parameters
+      const { channel, country, ymd, ...otherParams } = req.body
+
+      let apiBody: any = {
+        country,
+        ymd,
+        ...otherParams,
+      }
+
+      // Map frontend channel to API device parameter
+      if (channel) {
+        const deviceParams = mapChannelToApiParams(channel)
+        apiBody = { ...apiBody, ...deviceParams }
+      }
+
+      const response: AxiosResponse = await axios.post(
+        'https://api.scope3.com/v2/measure?fields=all&includeRows=true&framework=scope3&latest=true',
+        apiBody,
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+          },
+        }
+      )
+
+      // Send back the response from the external API
+      res.status(response.status).json(response.data)
+    } catch (error) {
+      console.error('Error forwarding request:', error)
+
+      // Handle error responses
+      if (error && typeof error === 'object' && 'response' in error) {
+        const axiosError = error as AxiosError
+        if (axiosError.response) {
+          res.status(axiosError.response.status).json(axiosError.response.data)
+        } else {
+          res.status(500).json({ message: 'Network error' })
+        }
+      } else {
+        res.status(500).json({ message: 'Internal server error' })
+      }
+    }
+  }
+)
+
+// Candidate will add additional endpoints here as needed
+
+// Only start server if not in test environment
+if (process.env.NODE_ENV !== 'test') {
+  app.listen(PORT, () => {
+    console.log(`Server is running on http://localhost:${PORT}`)
+    console.log('Available endpoints:')
+    console.log('  POST /forward - Forward requests to Scope3 API')
+  })
+}
+
+// Export app for testing
+export default app

backend/jest.config.js

@@ -0,0 +1,17 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
+  transform: {
+    '^.+\\.ts$': 'ts-jest',
+  },
+  collectCoverageFrom: [
+    '**/*.ts',
+    '!**/*.d.ts',
+    '!**/node_modules/**',
+    '!**/tests/**',
+  ],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov', 'html'],
+}