Building and Testing the OctoCAT Supply Chain Application

This guide provides instructions for building, running, and testing the OctoCAT Supply Chain Management application, which consists of an API component and a React Frontend.

Prerequisites#

• Node.js 24 (the workshop's pinned runtime)
• npm (latest version recommended)
• Docker/Podman (optional, for containerization)

Installation#

1. Fork and clone the standalone workshop repository (see setup).
2. Change into src/ before using any make commands below.
3. Install dependencies:

make install

Building the Application#

Using Make Commands#

You can build the entire application or its individual components using the following commands:

# Build both API and Frontend components
make build

# Build only the TypeScript API component
make build-ts

# Build only the Frontend component
make build-frontend

Alternatively, if you're in the api-ts/ or frontend/ directories, you can use npm commands directly:

cd api-ts && npm run build
cd frontend && npm run build

Database management#

# Initialize DB schema (runs migrations)
make db-init

# Seed sample data
make db-seed

Alternatively, if you're in the api-ts/ directory, you can use npm commands directly:

cd api-ts
npm run db:init
npm run db:seed

Environment variables:

• DB_FILE: path to SQLite database file (default: api-ts/data/app.db)
• DB_ENABLE_WAL: enable WAL mode (default: true)
• DB_FOREIGN_KEYS: enforce foreign keys (default: true)
• DB_TIMEOUT: busy timeout in ms (default: 30000)

Using VS Code Tasks#

VS Code tasks have been configured to streamline the build process:

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) to open the Command Palette
2. Type Tasks: Run Task and select it
3. Choose from the following tasks:
   • Build All: Builds both API and Frontend components
   • Build API: Builds only the API component
   • Build Frontend: Builds only the Frontend component

Alternatively, you can press Ctrl+Shift+B (or Cmd+Shift+B on macOS) to run the default build task (Build All).

Running the Application#

Using Make Commands#

# Start both API and Frontend in development mode with hot reloading
make dev

# Start only the TypeScript API in development mode
make dev-api-ts

# Start only the Frontend in development mode
make dev-frontend

# Start the application in production mode
make start

Alternatively, if you're in the api-ts/ or frontend/ directories, you can use npm commands directly:

cd api-ts && npm run dev
cd frontend && npm run dev

Using VS Code Debugger#

1. Open the Debug panel (Ctrl+Shift+D or Cmd+Shift+D on macOS)
2. Select Start API & Frontend from the dropdown menu
3. Click the green play button or press F5

This will start both the API and Frontend in development mode with the integrated terminal, allowing you to see the console output.

Testing the Application#

Running Tests#

# Run all tests
make test

# Run TypeScript API tests only
make test-ts

# Run frontend tests only
make test-frontend

Alternatively, if you're in the api-ts/ or frontend/ directories, you can use npm commands directly:

cd api-ts && npm run test
cd frontend && npm run test

Linting#

# Run linting checks
make lint

Alternatively, if you're in the api-ts/ or frontend/ directory, you can use npm commands directly:

cd frontend && npm run lint

cd api-ts && npm run lint

Additional Information#

Port Configuration#

The API runs on port 3000 by default, and the frontend runs on port 5137. The Vite development server proxies /api to port 3000, so the browser only needs the forwarded frontend port. It permits the exact forwarded hostname derived from CODESPACE_NAME and GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN, rather than disabling Vite's host protection. Keep both ports private in Codespaces; do not publish an unauthenticated workshop API. An explicit VITE_API_URL overrides the proxy.

For Docker, the sample compose maps API to 3000 and frontend to 3001.

Docker Deployment#

The project includes Dockerfiles for both API and Frontend components and a docker-compose.yml file for easy containerized deployment:

# Build and start using Docker Compose
docker-compose up --build