firefrost-operations-manual/docs/templates/implementation-guide-template.md

# [Project Name] — Complete Implementation Guide

**Version:** 1.0  
**Created:** [Date]  
**Authors:** [Names and roles]  
**Purpose:** Cold-start handoff document — any AI or developer can implement [project] from this single document.

---

## Table of Contents

1. [Project Overview](#1-project-overview)
2. [Architecture Decisions](#2-architecture-decisions)
3. [Complete File Structure](#3-complete-file-structure)
4. [Database Schema](#4-database-schema)
5. [All Code](#5-all-code)
6. [Configuration Files](#6-configuration-files)
7. [Deployment Infrastructure](#7-deployment-infrastructure)
8. [Implementation Checklist](#8-implementation-checklist)
9. [Migration/Integration](#9-migrationintegration)
10. [Emergency Contacts](#10-emergency-contacts)
11. [Document History](#11-document-history)

---

## 1. Project Overview

### What is This Project?

[1-2 paragraphs describing the project purpose]

### Users

| Name/Role | Description | Access Level |
|-----------|-------------|--------------|
| [User 1] | [Description] | [Access] |
| [User 2] | [Description] | [Access] |

### Key Characteristics

- **Stack:** [Technologies used]
- **Auth:** [Authentication method]
- **Design:** [Design requirements/theme]
- **Deployment:** [Where it lives]

### Brand/Design Requirements (if applicable)

| Element | Value | Usage |
|---------|-------|-------|
| [Color 1] | `#HEXCODE` | [Usage] |
| [Color 2] | `#HEXCODE` | [Usage] |

---

## 2. Architecture Decisions

### Decision 1: [Title]

**Options Considered:**
1. [Option A] — [Pros/Cons]
2. [Option B] — [Pros/Cons]

**Decision:** [What was chosen]

**Rationale:** [Why this option]

### Decision 2: [Title]

[Repeat pattern]

### Constraints & Requirements

- [Constraint 1]
- [Constraint 2]

### Dependencies

| Dependency | Version | Purpose |
|------------|---------|---------|
| [Package] | [Version] | [Why needed] |

---

## 3. Complete File Structure

```
/path/to/project/
├── folder/
│   ├── file.js              # [Description]
│   └── another.js           # [Description]
├── config/
│   └── settings.json        # [Description]
└── README.md                 # [Description]
```

---

## 4. Database Schema

### Migration Order

1. `001_[name].sql` — [Description]
2. `002_[name].sql` — [Description]

### `migrations/001_[name].sql`

```sql
-- Description of what this migration does

CREATE TABLE IF NOT EXISTS table_name (
    id SERIAL PRIMARY KEY,
    column_name VARCHAR(100) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes
CREATE INDEX IF NOT EXISTS idx_name ON table_name(column_name);

-- Seed data (if any)
INSERT INTO table_name (column_name) VALUES 
('value1'),
('value2')
ON CONFLICT DO NOTHING;
```

### `migrations/002_[name].sql`

```sql
-- [Continue pattern]
```

---

## 5. All Code

### `src/index.js`

```javascript
// Main entry point
// [Complete code here]
```

### `src/module/file.js`

```javascript
// [Complete code here]
```

### `src/views/template.ejs`

```html
<!-- [Complete code here] -->
```

[Continue for ALL files in the structure]

---

## 6. Configuration Files

### Environment Variables (`.env`)

```env
# Database
DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=

# Authentication
AUTH_SECRET=

# External Services
SERVICE_API_KEY=

# Application
PORT=3000
NODE_ENV=production
BASE_URL=https://example.com
```

### PM2 Configuration (`ecosystem.config.js`)

```javascript
module.exports = {
  apps: [{
    name: "app-name",
    script: "./src/index.js",
    watch: false,
    env: {
      NODE_ENV: "production",
      PORT: 3000
    }
  }]
};
```

### Nginx Configuration

```nginx
server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 7. Deployment Infrastructure

### Server Information

| Server | IP | Role |
|--------|-----|------|
| [Server 1] | [IP] | [Role] |
| [Server 2] | [IP] | [Role] |

### DNS Setup

| Record | Type | Value |
|--------|------|-------|
| [subdomain] | A | [IP] |

### Bootstrap Script

```bash
# System updates
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y [packages]

# [Continue with all setup commands]
```

### SSL Certificate

```bash
sudo certbot --nginx -d example.com
```

### Firewall Rules

```bash
sudo ufw allow [port]
sudo ufw allow from [IP] to any port [port]
```

---

## 8. Implementation Checklist

### Phase 0: Infrastructure Setup

- [ ] [Task 1]
- [ ] [Task 2]
- [ ] [Task 3]

### Phase 1: Core Foundation

- [ ] [Task 4]
- [ ] [Task 5]
- [ ] [Task 6]

### Phase 2: Features

- [ ] [Task 7]
- [ ] [Task 8]

### Phase 3: Testing & Launch

- [ ] [Task 9]
- [ ] [Task 10]

---

## 9. Migration/Integration

### Existing Systems Affected

| System | Impact | Migration Steps |
|--------|--------|-----------------|
| [System 1] | [Impact] | [Steps] |

### Data Migration

1. [Step 1]
2. [Step 2]

### Rollback Procedure

1. [Step 1]
2. [Step 2]

---

## 10. Emergency Contacts

If the primary implementer is unavailable:

1. **[Backup 1]** — [Why they can help, how to contact]
2. **[Backup 2]** — [Why they can help, how to contact]
3. **New AI session** — Start fresh with this document

---

## 11. Document History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.0 | YYYY-MM-DD | [Name] | Initial creation |

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️