Tony's World of Chips Development Assistant

Expert guidance for working with the Tony's World of Chips e-commerce application codebase.

What This Skill Does

This skill provides comprehensive guidance for developing, testing, deploying, and maintaining Tony's World of Chips—a demonstration e-commerce application built as a TypeScript monorepo with Docker containerization. It covers API development, web frontend, database management, E2E testing, CI/CD orchestration, and System Initiative policy compliance checking.

Project Context

Tony's World of Chips is a full-stack e-commerce storefront application that sells potato chips. It demonstrates modern web application architecture with:

Instructions for AI Agent

When working with this codebase, follow these guidelines:

1. Understanding the Monorepo Structure

**Key principle**: Both packages extend the root TypeScript config. When working with Docker builds, ensure root `tsconfig.json` is copied to resolve extends paths.

2. Development Workflow

**Running services locally:**

```bash

API development (from packages/api/)

npm run dev # Port 3000

npm test # Jest tests

npm run test:watch # Watch mode

npx prisma studio # Database GUI

Web development (from packages/web/)

npm run dev # Port 3001

npm run lint # ESLint

E2E tests (from root)

npm run test:e2e # Run all Playwright tests

npm run test:e2e:ui # Interactive UI mode

```

**Using Docker Compose:**

```bash

Build and start all services

npm run build:local # Build images with latest tag

npm run docker:up # Start services

npm run docker:logs # View logs

Run E2E tests against Docker services

npm run docker:test:e2e

Cleanup

npm run docker:down

```

3. Database Operations

**All database commands run from `packages/api/`:**

```bash

Create and apply migration

npx prisma migrate dev --name descriptive_name

Generate Prisma Client (after schema changes)

npx prisma generate

Seed database with sample data

npx prisma db seed

Open Prisma Studio GUI

npx prisma studio

Production migration deployment

npx prisma migrate deploy

```

**Schema location**: `packages/api/prisma/schema.prisma`

**Models**: Product, CartItem, Order

**Authentication modes**:

- Controlled by `DB_USE_IAM_AUTH` environment variable

- Tokens auto-refresh every 14 minutes via `src/config/secrets.ts`

4. Docker Architecture

**Image Tags**:

**Building specific images:**

```bash

All images

npx tsx ci/main.ts build-local all

Individual images

npx tsx ci/main.ts build-local api

npx tsx ci/main.ts build-local web

npx tsx ci/main.ts build-local e2e

```

**Using versioned tags:**

```bash

IMAGE_TAG=20250115120000-abc123 docker-compose up

```

**Important Docker considerations**:

5. API Architecture (`packages/api/`)

**Entry point**: `src/index.ts`

**Routes** (all under `/api/*` prefix):

**Database client**: `src/config/database.ts`

**Testing**: Jest with supertest in `src/__tests__/`

**AWS Integration**:

6. Web Architecture (`packages/web/`)

**Entry point**: `src/index.ts`

**Routes**:

**Session Management**:

**Views**: EJS templates in `views/` directory

**Service Layer**: `src/services/` contains Axios-based API clients

**Environment Variables**:

7. E2E Testing with Playwright

**Test files**:

**Configuration**: `playwright.config.ts` at root level

**Environment Variables**:

**Running tests**:

```bash

Locally (requires running services)

npm run test:e2e

In Docker container

npm run docker:test:e2e

Against remote environments

API_URL=https://api.example.com WEB_URL=https://www.example.com npm run docker:test:e2e

With custom options and result persistence

docker run --rm \

-e API_URL=https://api.example.com \

-e WEB_URL=https://www.example.com \

-v $(pwd)/test-results:/app/test-results \

-v $(pwd)/playwright-report:/app/playwright-report \

tonys-chips/e2e:latest

```

8. CI/CD Orchestration

**Entry point**: `ci/main.ts` - TypeScript CLI for all CI/CD operations

**Available commands**:

**Usage pattern**:

```bash

npx tsx ci/main.ts <command> [args]

Or via npm scripts:

npm run ci:<command>

```

9. System Initiative Policy Compliance

**Policy structure**: Markdown files in `policy/` directory with YAML frontmatter

**Policy file format**:

```markdown

Policy Title

Policy

Policy description and requirements...

Exceptions

Any exceptions to the policy...

Source Data

System Initiative

```yaml

query-name: "schema:AWS*"

another-query: "schema:AWS::EC2::*"

```

Output Tags

```yaml

tags:

- tag1

- tag2

```

```

**Running policy checks**:

```bash

Single policy

npx tsx ci/main.ts check-policy policy/my-policy.md

With custom output path

npx tsx ci/main.ts check-policy policy/my-policy.md --output ./reports/report.md

Or via npm script

npm run ci:check-policy policy/my-policy.md

```

**Required environment variables**:

**Policy check pipeline**:

1. Extract Policy - Claude parses markdown to structured data

2. Collect Source Data - Query System Initiative API

3. Evaluate Policy - Claude evaluates components against requirements

4. Generate Report - Markdown report with deep links to SI components

**GitHub Actions**: `policy-check.yml` workflow runs all policies on manual trigger, posts results to issues, and uploads reports as artifacts.

10. Code Modification Guidelines

When making changes to this codebase:

**API changes**:

**Web changes**:

**Docker changes**:

**E2E test changes**:

**CI/CD changes**:

11. Common Tasks

**Add a new API endpoint**:

1. Define route handler in appropriate file under `packages/api/src/routes/`

2. Mount route in `src/index.ts`

3. Add service method in web package if needed

4. Write integration tests

5. Update E2E tests if user-facing

**Add a new database table**:

1. Update `packages/api/prisma/schema.prisma`

2. Run `npx prisma generate`

3. Create migration: `npx prisma migrate dev --name add_table_name`

4. Update seed data in `prisma/seed.ts` if needed

5. Update TypeScript types and API routes

**Add a new web page**:

1. Create EJS template in `packages/web/views/`

2. Add route handler in `packages/web/src/index.ts`

3. Create service methods for API calls

4. Add static assets if needed

5. Write E2E tests for the page

**Debug session issues**:

1. Check Valkey connectivity: `docker-compose logs valkey`

2. Verify `REDIS_URL` environment variable

3. Check session secret configuration

4. Test session persistence across requests

5. Review `express-session` middleware configuration

**Troubleshoot database connections**:

1. Check PostgreSQL health: `docker-compose logs postgres`

2. Verify `DATABASE_URL` format

3. For IAM auth issues, check token refresh logic in `src/config/secrets.ts`

4. Test connection with `npx prisma db pull`

5. Review Prisma connection pooling settings

Examples

Example 1: Adding a New Product Category Field

```bash

1. Update Prisma schema

Edit packages/api/prisma/schema.prisma, add category field to Product model

2. Generate Prisma Client

cd packages/api

npx prisma generate

3. Create migration

npx prisma migrate dev --name add_product_category

4. Update seed data

Edit prisma/seed.ts to include category values

5. Run seed

npx prisma db seed

6. Update API routes if needed

Edit src/routes/products.ts to handle category filtering

7. Run tests

npm test

```

Example 2: Running E2E Tests Against Staging Environment

```bash

Build E2E image with specific tag

npx tsx ci/main.ts build sandbox e2e 20250115120000-abc123

Run tests against staging URLs

API_URL=https://staging-api.example.com \

WEB_URL=https://staging-web.example.com \

docker run --rm \

-e API_URL=https://staging-api.example.com \

-e WEB_URL=https://staging-web.example.com \

-v $(pwd)/test-results:/app/test-results \

-v $(pwd)/playwright-report:/app/playwright-report \

tonys-chips/e2e:20250115120000-abc123

View report

npm run test:e2e:report

```

Example 3: Checking Infrastructure Policy Compliance

```bash

Set required environment variables

export SI_API_TOKEN="your-si-token"

export SI_WORKSPACE_ID="your-workspace-id"

export ANTHROPIC_API_KEY="your-anthropic-key"

Run single policy check

npx tsx ci/main.ts check-policy policy/security-groups.md

Run check with custom output

npx tsx ci/main.ts check-policy policy/security-groups.md \

--output ./reports/security-groups-$(date +%Y%m%d).md

View generated report

cat ./reports/security-groups-*.md

```

Important Notes