## Elevator Pitch
> YoloCorp is a developer challenge platform where you design backends your way
through multi-episode projects with persistent data, drifting requirements,
and a corporate fever-dream storyline.
>
> Think LeetCode × real-world production × text adventure × The Office.

## Core Concepts
Each challenge is structured as a **Project** composed of sequential **Episodes**.

You progress by implementing code, passing tests, and unlocking the next **Episode**.

All the available challenges are listed in the [Innovation Portfolio](/projects)

### Project

A Project is a complete challenge path. It contains:
- A sequence of Episodes
- A shared data folder that persists across Episodes

### Episode

An Episode is a self-contained step in the Project.

Each Episode contains:
- A Client TypeScript interface describing the behavior the client must implement
- Episode-specific tests (downloaded episode by episode)

Completing an Episode unlocks the next one.

## Developer flow

All interactions are performed using the [YOLO CLI](/downloads)

### 1. Enroll in a Project
Run ```yolo enroll```. This command will :

1. Lets you pick a Project
1. Creates the local project directory
1. Downloads the first Episode
1. Generates initial client files

Something looking like that:
```
.
├── backend
│   └── Dockerfile // a minimal backend Dockerfile you are expected to customize
├── client
│   ├── src
│   │   ├── toImplement.ts // the required interface for the current Episode
│   │   └── userImplementation.ts // your implementation
│   └── tsconfig.json
└── user-compose.yml // your own docker compose file
```

### 2. Implement the client interface

For each Episode, the CLI generates a new `toImplement.ts` file overwritting the previous one.

This interface is voluntarily kept as business oriented as possible and uses the Command-query separation (CQS) principle.

Your task is to implement all its functions in `userImplementation.ts`.

### 3. Build your backend

You are free to design and implement any backend architecture, including:
- REST, GraphQL, RPC, direct DB access, microservices etc.
- Any language or framework
- Any storage engine (SQL, NoSQL, files, in-memory with snapshots, etc.)

Your backend must be defined in user-compose.yml and all your services must use the Docker network `yolo-network`
(the backend service will automatically live within it).

> NB : You can define as many services as you want, but you must have at least one service named **backend** that exposes a healthcheck when it’s ready for writes (i.e migrations have been executed).
> The client will wait for this service to become [Healthy](https://docs.docker.com/reference/compose-file/services/#healthcheck) before running the tests.

### 4. The deploy command:
1. Builds a Docker Compose environment containing :
    - Your client code running in a Node container generated by the CLI
    - Your backend container(s)
1. Downloads tests for the current Episode
1. Copies the Episode’s tests into the client container and executes them from inside that container
1. Reports success or failure

If all tests pass:
- The next Episode is downloaded automatically
- Your last achieve episode is saved on our server
- All the docker volumes you used are saved locally in a `./.snapshots` folder (DO NOT DELETE THEM)

> NB 1 : YOLO applies a challenge-specific Compose file (e.g. episode-compose.yml) on top of your user-compose.yml using standard Docker Compose merge semantics.

> NB 2 : Your client code will run inside the Docker Compose environment it should reach your other services using the docker network `yolo-network`.

### 5. Repeat until the Project is complete

Work Episode by Episode until you reach the end of the project or the last published Episode

If you reach the last published episode, the date for the release of the next one will be displayed.

You can run `yolo check-episode` later on to get it

## Why YOLO Corp Is Unique

### 1. Persistent Data Across Episodes

Your environment and data are not reset between Episodes.
If Episode N introduces new requirements, you may need to migrate data created in Episodes 1…N−1.

This encourages real-world engineering practices such as migrations, contracts-first design, and data lifecycle management.

### 2. Backend Freedom

You define:
- API shape
- Database schema
- Internal domain model
- Deployment layout inside Docker

As long as your client implementation satisfies the tests, everything else is up to you.


### 3. Realistic DevOps Workflow

Each deploy simulates:
- Local development → build → containerized tests
- Black-box testing
- Data continuity

## Tests & Execution Environment
- Tests are downloaded when running yolo deploy
- All tests run in a fully isolated Docker Compose setup
- Your client code runs in a dedicated container
- Your backend runs in one or multiple containers you define
- The tests exercise your backend only through your client implementation, never by calling your backend directly.
- All containers communicate over a shared Docker network. so the client and backend communicate using Compose service names as hostnames.
- Data volumes persist across Episodes (and are expected to)

# FAQ

### The backend can't reach my other services
The backend service is automatically deployed in the docker `yolo-network` so your services must be
in it too.

Something like that :
```yaml
    myotherservice:
      image: myotherimage
      networks:
        - yolo-network
```

### Can I inspect logs?

Yes, after a `yolo deploy` all containers are stopped but not destroyed so logs are available using
```
docker logs <my service>
```

To see client logs, the test runner pipes stderr, so you should see output like:

```ts
console.warn("warning from client")
console.error("woops from client")
```

### How do I implement an healthchek for the backend ?
A simple solution can be to define in your `user-compose.yml`

```yaml
service:
    backend:
        healthcheck:
            test: ["CMD", "wget", "--spider", "-q", "http://127.0.0.1:3000/health"]
            interval: 30s
            timeout: 10s
            retries: 3
```

and just return a `200` for a `GET /health` in your service.
This assumes your service listens on `:3000`

> NB: alpine doesn't ship with curl so we use the more widely available wget command

### In which Docker image will my client code run?
Currently, the CLI uses

```docker
FROM node:lts-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .

CMD ["tail", "-f", "/dev/null"]
```