asle/SUBMODULE_SETUP.md

# Submodule Setup Guide

## Current Structure (Option 3)

This repository follows **Option 3** structure:
- **Backend** (`backend/`): Monorepo containing API, middleware, jobs, services, and GraphQL - all tightly coupled components
- **Contracts** (`contracts/`): Currently a regular directory, ready to be converted to a submodule
- **Frontend** (`frontend/`): Currently a regular directory, ready to be converted to a submodule

## Why This Structure?

### Backend as Monorepo
The backend components (API routes, middleware, jobs, services) are kept together because:
- They share the same `package.json` and dependencies
- They use the same database schema (Prisma)
- They deploy as a single service
- They have tight coupling and shared business logic
- No independent versioning needed

### Contracts & Frontend as Submodules (When Ready)
These components can be submodules because:
- They have independent tooling (Foundry vs Next.js)
- They can have separate release cycles
- They may be developed by different teams
- They can be reused in other projects

## Converting to Submodules

### Option A: Automated Setup (Recommended)

Use the provided script with a GitHub token to automatically create repositories and set up submodules:

```bash
# Set your GitHub token (create one at https://github.com/settings/tokens)
export GITHUB_TOKEN=your_github_token_here

# Run the setup script (optionally specify org/username)
./scripts/setup-submodules.sh [your-github-org-or-username]
```

The script will:
1. ✅ Create GitHub repositories for contracts and frontend
2. ✅ Push the code to those repositories
3. ✅ Convert them to git submodules
4. ✅ Commit the submodule configuration

**Required GitHub Token Permissions:**
- `repo` scope (to create repositories and push code)

### Option B: Manual Setup

When you're ready to convert `contracts/` and `frontend/` to proper git submodules, follow these steps:

#### Prerequisites
1. Create remote repositories for `contracts` and `frontend` (e.g., on GitHub, GitLab, etc.)
2. Push the existing code to those remotes

#### Steps

1. **Remove current directories from main repo:**
   ```bash
   git rm -r contracts frontend
   git commit -m "Remove contracts and frontend before submodule conversion"
   ```

2. **Add as submodules:**
   ```bash
   git submodule add <contracts-remote-url> contracts
   git submodule add <frontend-remote-url> frontend
   ```

3. **Commit the submodule configuration:**
   ```bash
   git add .gitmodules contracts frontend
   git commit -m "Add contracts and frontend as submodules"
   ```

### Working with Submodules

**Cloning the repository:**
```bash
git clone --recurse-submodules <repo-url>
# Or if already cloned:
git submodule update --init --recursive
```

**Updating submodules:**
```bash
git submodule update --remote
```

**Making changes in submodules:**
```bash
cd contracts
# Make changes, commit, push
cd ..
git add contracts
git commit -m "Update contracts submodule"
```

## Current Status

- ✅ Backend is a unified monorepo (API, middleware, jobs together)
- ✅ Contracts and frontend are regular directories (no nested .git)
- ⏳ Ready to convert to submodules when remotes are created