# Karma Subito & Marketing Admin Panel

This document contains instructions for setting up the development environment, running the project, making contributions via Pull Requests (PR), and triggering the CI/CD pipeline.

## 1. Main Setup Instructions

### Prerequisites
- **Node.js**: v18 or higher (v20+ recommended)
- **Package Manager**: pnpm (v9+ recommended)
- **Docker** (Optional, for containerized test builds)

### Initial Installation
1. Clone the repository and navigate to the project root.
2. Install all dependencies using pnpm workspace commands:
   ```bash
   pnpm install
   ```
   *(Note: This uses Turborepo to map out inter-dependencies efficiently)*
3. Ensure you have the necessary `.env` files set up within each respective folder under `apps/` before booting apps locally (e.g., `apps/core/.env`, `apps/marketing-cms/.env`). 

---

## 2. Development (Dev) Instructions

We use **Turborepo** (`turbo run dev`) to manage monorepo task execution.

### Running Everything
To spin up all development servers (Admin Console, Core API, CMS, Chatbot, etc.) at once:
```bash
pnpm run dev
```

### Running Specific Services
If you want to only run specific services locally to save overhead, you can use the predefined helper scripts:

- **Marketing Stack ONLY** (CMS + Landing Page):
  ```bash
  pnpm run dev:marketing
  ```
- **Chatbot ONLY**:
  ```bash
  pnpm run dev:chatbot
  ```

Alternatively, you can manually filter a specific app using turbo:
```bash
pnpm turbo run dev --filter=@karma/core
pnpm turbo run dev --filter=@karma/admin-console
pnpm turbo run dev --filter=marketing-cms
```

### Linting & Formatting
Before pushing code, make sure to format and typecheck:
```bash
pnpm run format
pnpm run lint
pnpm run typecheck
```

---

## 3. How to Raise a PR

1. **Create a new branch** off `dev` (or the respective milestone branch). Name your branch descriptively (e.g., `feature/update-cookie-session` or `fix/cms-404-issue`).
2. Make your commits adhering to standard conventional commits.
3. Push the branch to the repository.
4. **Open a Pull Request** targeting the `dev` branch.
5. In your PR description, explain what changes were made.
6. **Important for Deployments:** Format the PR Title explicitly to include the deployment tags. This is what signals to the Github Action *where* and *what* to deploy (see CI/CD section below).

---

## 4. How to Trigger CI/CD & Deployments

Deployments are strictly automated via GitHub Actions (`.github/workflows/deploy.yml`), and they ONLY trigger when a Pull Request is **merged into the `dev` branch**.

### Setting the PR Title for Deployments
The GitHub Actions workflow listens for a specific tag inside the **Pull Request Title**. If the tag is present when the PR is merged, it extracts the target apps and kicks off the SSH deployment.

The trigger tag is: **`#dev-release:`**

#### Examples of valid PR titles for deployment:
- **Deploying EVERYTHING:**
  `Update marketing styles #dev-release: all`
- **Deploying specific apps only (comma-separated):**
  `Refactor core logic #dev-release: core,admin-console`
  `Fix CMS bugs #dev-release: marketing-cms`

#### How it works:
1. When the PR is merged to `dev`, the action validates the title.
2. It strips out whitespace and scopes (like `@karma/`).
3. It passes the app list down to the deployment server via SSH (e.g., `./deploy.sh <apps>`).
4. If `#dev-release: all` is provided, it attempts to deploy `nextjs core admin`.

*Warning: If the PR title does **not** contain the `#dev-release:` tag when you click merge, the CI/CD deployment will deliberately be skipped!*