> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Guide

> Developer guide for setting up OASM development environment, running services, and database management

## Development

### Start Services

To start all services (API, Console) simultaneously, use the task command from the root directory:

```bash theme={null}
task dev
```

### Run Workers

To run workers locally, use the task command from the root directory:

```bash theme={null}
task worker:dev replicas=1 maxJobs=10 apiKey=your_workspace_apikey
```

### Generate Function Call API

To run generate function call api, use the task command from the root directory:

```bash theme={null}
task gen-api
```

## Database

### Setup

The `task init` command automatically starts a PostgreSQL container using Docker. The database connection details are configured in `core-api/.env`.

If you prefer to use your own PostgreSQL instance, update the `core-api/.env` file accordingly.

### Migration

#### Overview

Database migrations are managed using TypeORM. The migration scripts are defined in `core-api/taskfile.yml` and can be executed using the task commands.

#### Run Migrations

##### Run All Pending Migrations

This command executes all pending database migrations:

```bash theme={null}
task migration:run
```

This will:

* Connect to the PostgreSQL database
* Check for pending migrations in the `migrations` table
* Run all new migrations that haven't been applied yet

##### Generate Migration

To generate a new migration with a custom name:

```bash theme={null}
task migration:generate name=YourMigrationName
```

For example:

```bash theme={null}
task migration:generate name=AddUserTable
```

This will create a new migration file in `core-api/src/database/migrations/`.

##### Revert Last Migration

To rollback the most recently executed migration:

```bash theme={null}
task migration:revert
```

**Note:** This will only revert one migration at a time. Repeat if needed.

### Migration with Docker

#### Using Docker Compose

If you prefer to run migrations using Docker (useful when not running PostgreSQL locally):

```bash theme={null}
docker compose up migration
```

This will:

1. Start the PostgreSQL container (if not running)
2. Run the migration service
3. Execute all pending migrations
4. Automatically remove the migration container after completion
5. Start the core-api service after migrations complete

#### Manual Run

To run migration container manually and keep it for debugging:

```bash theme={null}
docker compose run --rm migration
```

The `--rm` flag ensures the container is removed after it stops.

## Development Conventions

### Code Style

* **Core API (NestJS):** Uses ESLint and Prettier for code formatting and linting. Currently, you need to run `npm run lint` and `npm run format` directly from the `core-api` directory. Consider creating a task to wrap these commands for convenience.
* **Console (React):** Uses ESLint and Prettier. Currently, you need to run `npm run lint` directly from the `console` directory. Consider creating a task to wrap this command for convenience.
* **Workers (Bun):** Likely follows standard TypeScript conventions. You may need to run linting/formatting commands directly from the `worker` directory.

### Testing

* **Core API:** Uses Jest for testing. Currently, you need to run the following commands directly from the `core-api` directory:

  * Run unit tests: `npm run test`
  * Run tests in watch mode: `npm run test:watch`
  * Run end-to-end tests: `npm run test:e2e`
    Consider creating tasks to wrap these commands for convenience.

## Docker

### Using Docker Compose

To run the entire stack, including the database, using Docker Compose:

```bash theme={null}
task docker-compose
```

This command uses `docker-compose.yml` to orchestrate containers.