# Two-Repository Architecture

**Purpose:** Separate tech stack infrastructure from custom application code for easy server migration and deployment.

---

## Overview

Instead of one monolithic repository, split into two:

| Repository | Contains | Changes | Deployment |
|------------|----------|---------|------------|
| `igny8-stack` | Docker, configs, dependencies | Rarely | Clone once per server |
| `igny8-app` | Your custom business logic | Frequently | Copy to deploy |

---

## Why This Architecture?

### Current Problem
- Everything mixed together (Dockerfiles, configs, your code)
- To deploy to new server, must copy everything
- Hard to distinguish "what's mine" vs "what's framework"

### Solution Benefits
- **Clean separation**: Stack vs App code
- **Easy migration**: Just copy app folder after stack is installed
- **Version independence**: Update stack without touching app
- **Reusable stack**: Same stack can run different apps on different servers

---

## How It Works

### Server Structure After Setup

```
/data/
├── stack/
│   └── igny8-stack/          # Cloned from stack repo (read-only)
│
├── app/
│   └── igny8/                # Your app code + symlinks to stack
│       ├── backend/
│       │   ├── Dockerfile        → symlink to stack
│       │   ├── requirements.txt  → symlink to stack
│       │   ├── manage.py         → symlink to stack
│       │   └── igny8_core/       # YOUR CODE
│       │
│       └── frontend/
│           ├── package.json      → symlink to stack
│           ├── vite.config.ts    → symlink to stack
│           └── src/              # YOUR CODE
│
└── logs/
```

### Symlinks Explained

The `install.sh` script creates symbolic links from your app folder to the stack folder. This means:
- Stack files (Dockerfile, package.json, etc.) live in one place
- Your app folder references them via symlinks
- Docker sees a complete project structure
- You only manage your custom code

---

## Migration Workflow

### On New Server

```
Step 1: Install Stack (one-time)
────────────────────────────────
cd /data/stack
git clone https://your-repo/igny8-stack.git
cd igny8-stack
./install.sh

Step 2: Deploy Your App
────────────────────────────────
cd /data/app
git clone https://your-repo/igny8-app.git igny8
# OR: rsync/scp from old server

Step 3: Configure
────────────────────────────────
cp .env.example .env
nano .env  # Set secrets, domains

Step 4: Start
────────────────────────────────
docker compose -f docker-compose.app.yml up -d
```

### Updating Existing Server

**Update app code only:**
```
cd /data/app/igny8
git pull
docker compose restart
```

**Update stack (rare):**
```
cd /data/stack/igny8-stack
git pull
./scripts/build-images.sh
docker compose -f /data/app/igny8/docker-compose.app.yml up -d
```

---

## What Goes Where?

### Stack Repo (igny8-stack)

Things that are **same for any Django+React app**:
- Dockerfiles
- Base requirements.txt / package.json
- Vite config, TypeScript config
- Docker compose templates
- Caddy config templates
- Utility scripts

### App Repo (igny8-app)

Things that are **specific to your application**:
- Django app code (models, views, serializers, business logic)
- React components, pages, stores
- App-specific static assets
- Documentation
- Environment config templates

---

## Key Principle

> If you deleted your app code and replaced it with a different Django+React app,
> would this file still make sense?
> - YES → Stack repo
> - NO → App repo

---

## Related Documentation

- [INFRASTRUCTURE-STACK.md](INFRASTRUCTURE-STACK.md) - Complete stack repo structure
- [IGNY8-APP-STRUCTURE.md](IGNY8-APP-STRUCTURE.md) - App repo structure