Code for Life Workspace Development

Expert guide for AI agents contributing to the Code for Life platform monorepo. This workspace contains frontend (TypeScript/React) and backend (Python/Django) services managed as Git submodules with centralized development scripts.

Architecture Overview

The Code for Life workspace is divided into three main sections:

All services are managed as Git submodules. Development is orchestrated through VS Code using the `codeforlife.code-workspace` file.

Critical Rule: Always Use Centralized Scripts

**NEVER run tools directly** (`yarn`, `vite`, `pipenv`, `pytest`, etc.). All development tasks MUST use the wrapper scripts in `/workspace/frontend/scripts` and `/workspace/backend/scripts`. These scripts ensure correct configurations and tool usage.

Frontend Development Workflow

All frontend commands should be run from within a service directory (e.g., `/workspace/frontend/portal`).

Setup

Install all dependencies for a frontend service:

```bash

/workspace/frontend/scripts setup

```

Development Server

Start the Vite development server:

```bash

/workspace/frontend/scripts run:dev

```

Quality Checks

Run all quality checks (linting, formatting, type checking, tests):

```bash

/workspace/frontend/scripts check

```

Testing

Run tests for the service:

```bash

/workspace/frontend/scripts test

```

Configuration

Backend Development Workflow

All backend commands should be run from within a service directory (e.g., `/workspace/backend/portal` or `/workspace/backend/sso`).

Setup

Set up Python environment and install dependencies:

```bash

/workspace/backend/scripts setup

```

Django Development Server

Start the local Django server:

```bash

/workspace/backend/scripts run:django

```

Quality Checks

Run all quality checks (imports, formatting, type checking, linting, migrations, tests):

```bash

/workspace/backend/scripts check

```

Testing

Run tests for the service:

```bash

/workspace/backend/scripts test

```

Database Migrations

Configuration

Git Submodule Workflow

The workspace uses Git submodules for service isolation:

1. **Make changes** within a service directory (e.g., `/workspace/frontend/portal`)

2. **Commit changes** within the submodule repository

3. **Update submodule reference** in the parent `codeforlife-workspace` repository

4. **Commit the reference change** in the parent repository

Project Conventions

1. **Script-first approach**: Use centralized scripts for ALL tasks

2. **Service-scoped work**: Run commands from within service directories

3. **Centralized configuration**: Tool configs live at workspace root

4. **Submodule awareness**: Always commit at both submodule and parent levels

5. **Quality gates**: All code must pass the `check` script before committing

Common Tasks

Adding a new frontend dependency

```bash

cd /workspace/frontend/portal

/workspace/frontend/scripts setup

```

Fixing linting issues

```bash

cd /workspace/frontend/portal

/workspace/frontend/scripts check

```

Running backend migrations

```bash

cd /workspace/backend/portal

/workspace/backend/scripts check

```

Full workspace quality check

Run `check` scripts in each active service directory.

Important Constraints