deafgain-website/cline_docs/gitWorkflow.md

# Git Workflow & Memory Bank

## Git Configuration

### Repository Information
- **Repository URL**: `https://gitea.sigd.net/chaulmark/deafgain-website`
- **Gitea Server**: gitea.sigd.net (private Gitea instance)
- **Username**: `eliza`
- **Authentication**: Personal Access Token
- **Current Token**: `3dba996c9eca5b6267f7cd1b0996a94aac1ac0d5` (created 3/5/2026)
- **Local Path**: `/Users/Eliza/DeafGain-website`
- **Main Branch**: `main`
- **Latest Commit**: `78aade0c94a4bad05e5b8ff95d025e0b68e17336`

### Token Permissions
The access token has been configured with:
- ✅ Read repository access
- ✅ Write repository access (for pushing changes)

### Git Remote Configuration
```bash
# Remote is already configured:
origin: https://eliza:3dba996c9eca5b6267f7cd1b0996a94aac1ac0d5@gitea.sigd.net/chaulmark/deafgain-website.git
```

## Common Git Workflows

### 1. Checking Repository Status
```bash
# Check current status
git status

# View current branch
git branch

# View remote branches
git branch -r
```

### 2. Pulling Latest Changes
```bash
# Pull from main branch (recommended before starting work)
git pull origin main

# Or simply
git pull
```

### 3. Viewing Changes History
```bash
# View recent commits (short format)
git log --oneline --graph --all -15

# View specific commit details
git show HEAD
git show <commit-hash>

# View changes between commits
git diff HEAD~1 HEAD
git diff <commit-hash1> <commit-hash2>

# View files changed in a commit
git show --stat HEAD
```

### 4. Making Changes
```bash
# After editing files, check what changed
git status
git diff

# Stage all changes
git add .

# Or stage specific files
git add src/pages/Services.tsx

# Commit changes with meaningful message
git commit -m "Add new feature: Interactive map updates"

# Push to remote repository
git push origin main
# Or simply
git push
```

### 5. Viewing File History
```bash
# View commit history for specific file
git log --oneline src/pages/Services.tsx

# View changes to a file over time
git log -p src/pages/Services.tsx

# Who changed what in a file
git blame src/pages/Services.tsx
```

### 6. Undoing Changes
```bash
# Discard changes to a file (before staging)
git checkout -- src/pages/Services.tsx

# Unstage a file (keep changes)
git reset HEAD src/pages/Services.tsx

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes - DANGEROUS)
git reset --hard HEAD~1
```

### 7. Working with Branches
```bash
# Create new branch
git checkout -b feature/new-feature

# Switch branches
git checkout main

# List all branches
git branch -a

# Delete branch
git branch -d feature/old-feature

# Push branch to remote
git push origin feature/new-feature
```

## Recent Commit History

### Latest Changes (as of 3/5/2026)
```
78aade0 (HEAD -> main) - Update interactive map: Add RID conference to Missoula MT and update ASLTA description
4755cd3 - Consolidate services into single DeafGain Consultants offering
a565932 - Remove service selection field from contact form
ae7c52d - Add anti-spam honeypot field and update contact form service options
a0cf3e9 - Update memory bank status summary with current system state
df6c696 - Fix email configuration: Update SMTP port to 587 and regenerate Gmail app password
379c4e1 - Add Parliamentarian service and update Austin TX event
8b2b421 - Update email configuration: change SMTP port to 2525
5d49c9e - Remove ADA-compliant transcripts service
67c775a - Add two locations
86096d9 - Switch to Missoula from Helena
b1e7d29 - Add rebuild flags
b214427 - Added geographic locations for upcoming events
```

## Git Authentication Troubleshooting

### If Access Token Expires or Needs Regeneration

1. **Generate New Token in Gitea:**
   - Log into https://gitea.sigd.net
   - Settings → Applications → Access Tokens
   - Delete old token
   - Generate new token with repository permissions
   - Copy the new token immediately

2. **Update Git Remote:**
   ```bash
   # Remove old remote
   git remote remove origin
   
   # Add new remote with new token
   git remote add origin https://eliza:NEW_TOKEN_HERE@gitea.sigd.net/chaulmark/deafgain-website.git
   
   # Verify remote
   git remote -v
   ```

3. **Test Connection:**
   ```bash
   git pull
   ```

### Common Authentication Issues

**Issue**: 403 Forbidden error
- **Cause**: Token doesn't have proper permissions or has expired
- **Solution**: Generate new token with `read:repository` and `write:repository` permissions

**Issue**: Username incorrect
- **Cause**: Using wrong Gitea username
- **Solution**: Username is `eliza` (not email address `eliza@deafgain.org`)

**Issue**: Token doesn't work
- **Cause**: Token permissions not properly configured
- **Solution**: Ensure both read and write repository permissions are enabled

## DeafGain Website Codebase Overview

### Project Architecture

```
DeafGain-website/
├── Frontend (React + TypeScript)
│   ├── src/
│   │   ├── pages/           # Main page components
│   │   ├── components/      # Reusable UI components
│   │   ├── api/            # API integration layer
│   │   ├── context/        # React context providers
│   │   └── lib/            # Utility functions
│   └── public/             # Static assets
│       ├── videos/         # Video files (.mp4)
│       ├── subtitles/      # WebVTT subtitle files
│       ├── transcriptions/ # Text transcripts
│       └── images/         # Images and thumbnails
│
├── Backend (Node.js + Express)
│   └── server.ts           # API server
│
├── Docker Configuration
│   ├── docker-compose.yml        # Production orchestration
│   ├── docker-compose.dev.yml    # Development environment
│   ├── Dockerfile                # Frontend container
│   ├── Dockerfile.api            # Backend container
│   ├── Dockerfile.dev            # Dev frontend container
│   └── Dockerfile.dev.api        # Dev backend container
│
└── Configuration Files
    ├── vite.config.ts            # Vite build configuration
    ├── tailwind.config.js        # Tailwind CSS config
    ├── tsconfig.json             # TypeScript config
    ├── nginx.conf                # Nginx configuration
    ├── default.conf              # Nginx reverse proxy
    └── .env                      # Environment variables
```

### Key Files and Their Purposes

#### Frontend Pages (`src/pages/`)
- **Home.tsx**: Landing page with hero section and overview
- **About.tsx**: Information about Eliza and DeafGain
- **Services.tsx**: Service offerings + interactive US map with conference locations
- **Resources.tsx**: Video library with 6 governance training videos
- **Contact.tsx**: Contact form with email notifications

#### Components (`src/components/`)
- **Layout/**: Navbar, Footer, Layout wrapper
- **VideoPlayer.tsx**: Custom video player with WebVTT subtitle support
- **SnowPeaks.tsx**: Animated background graphics
- **Toast.tsx**: Notification component

#### Backend (`server.ts` & `src/api/`)
- **server.ts**: Main Express API server
- **api/contact.ts**: Contact form endpoint with email sending
- **api/subscribe.ts**: Newsletter subscription endpoint
- **lib/email.ts**: Email service integration (Gmail SMTP)
- **lib/rate-limit.ts**: Rate limiting logic

### Important Patterns

#### 1. Video Resource Structure
Each video requires 4 files:
```
public/videos/video-name.mp4               # Video file
public/subtitles/video-name.vtt            # WebVTT subtitles
public/transcriptions/video-name.txt       # Full text transcript
public/images/thumbnails/video-name.png    # Thumbnail image
```

#### 2. Interactive Map Data
Location data structure in `Services.tsx`:
```typescript
const relationshipPoints: RelationshipPoint[] = [
  {
    coordinates: [-longitude, latitude],
    city: "City Name",
    state: "State",
    events: [{
      name: "Organization Acronym",
      description: "Full event description",
      startDate: "Month DD, YYYY",
      endDate: "Month DD, YYYY"
    }]
  }
]
```

#### 3. Environment Variables
Critical `.env` variables:
```env
NODE_ENV=production
GMAIL_USER=system@deafgain.org
GMAIL_PASS=gmail_app_password
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
REDIS_URL=redis://localhost:6379
API_URL=http://localhost:804
```

### Development Workflow

#### Making Changes to the Website

1. **Pull latest changes**
   ```bash
   git pull
   ```

2. **Make your changes**
   - Edit files as needed
   - Test locally with `pnpm dev`

3. **Check what changed**
   ```bash
   git status
   git diff
   ```

4. **Stage and commit**
   ```bash
   git add .
   git commit -m "Descriptive message about changes"
   ```

5. **Push to Gitea**
   ```bash
   git push
   ```

6. **Deploy to production**
   - Changes are pulled to production server
   - Docker containers rebuilt with `docker-compose up --build -d`

#### Adding New Videos

1. **Prepare files:**
   - Video: `public/videos/video-name.mp4`
   - Subtitles: `public/subtitles/video-name.vtt`
   - Transcript: `public/transcriptions/video-name.txt`
   - Thumbnail: `public/images/thumbnails/video-name.png`

2. **Update Resources.tsx:**
   ```typescript
   {
     id: 'video-name',
     title: 'Video Title',
     thumbnail: '/images/thumbnails/video-name.png',
     description: 'Description',
     category: 'Professional Development & Governance'
   }
   ```

3. **Commit and push:**
   ```bash
   git add public/videos/ public/subtitles/ public/transcriptions/ public/images/thumbnails/ src/pages/Resources.tsx
   git commit -m "Add new video: Video Title"
   git push
   ```

#### Updating Interactive Map

1. **Edit Services.tsx**
2. **Add new location to relationshipPoints array**
3. **Use exact coordinates from Google Maps**
4. **Commit and push changes**
5. **Docker must rebuild with `no_cache: true` flag**

### Production Deployment

#### Current Production Setup
- **URL**: https://deafgain.org/
- **Server**: 10.4.0.206 (behind Caddy reverse proxy)
- **Network**: caddy_network (172.22.0.0/16)
- **Containers**:
  - deafgain-website-web-1 (port 804)
  - deafgain-website-api-1 (port 3000)
  - deafgain-website-redis-1

#### Deployment Process
```bash
# On production server
cd /docker/websites/deafgain/
git pull
docker-compose up --build -d
docker-compose logs -f  # Monitor logs
```

### Common Tasks Reference

#### View Recent Changes
```bash
git log --oneline --graph --all -15
```

#### See What Files Changed in Last Commit
```bash
git show --stat HEAD
```

#### See Full Changes in Last Commit
```bash
git show HEAD
```

#### Compare Two Commits
```bash
git diff abc123 def456
```

#### Search Commit History
```bash
# Find commits by message
git log --grep="map"

# Find commits that changed a specific file
git log -- src/pages/Services.tsx

# Find commits by author
git log --author="eliza"
```

#### Undo Last Commit (Keep Changes)
```bash
git reset --soft HEAD~1
```

#### Discard All Local Changes
```bash
git reset --hard HEAD
git clean -fd
```

## Best Practices

### Commit Messages
- Use descriptive, clear messages
- Start with a verb (Add, Update, Fix, Remove)
- Be specific about what changed
- Examples:
  - ✅ "Add RID conference to Missoula MT on interactive map"
  - ✅ "Fix email SMTP configuration and update app password"
  - ❌ "Updates"
  - ❌ "Fixed stuff"

### Before Making Changes
1. Always `git pull` first
2. Check current status with `git status`
3. Review what you're about to commit with `git diff`

### After Making Changes
1. Test locally if possible
2. Review changes with `git status` and `git diff`
3. Commit with clear message
4. Push to remote
5. Verify on production if critical

### Working with Production
- Test changes locally before pushing
- Be cautious with Docker configuration changes
- Monitor logs after deployment
- Keep `.env` file secure (never commit)

## Security Notes

- **Never commit `.env` file** - contains sensitive credentials
- **Keep access token secure** - treat like a password
- **Regenerate token if exposed** - create new one immediately
- **Use app-specific passwords** - for Gmail integration
- **Review changes before pushing** - especially configuration files

## Quick Reference Commands

| Task | Command |
|------|---------|
| Pull latest changes | `git pull` |
| Check status | `git status` |
| View recent commits | `git log --oneline -15` |
| View last commit | `git show HEAD` |
| Stage all changes | `git add .` |
| Commit changes | `git commit -m "message"` |
| Push to remote | `git push` |
| Undo last commit (keep changes) | `git reset --soft HEAD~1` |
| Discard local changes | `git reset --hard HEAD` |
| View file history | `git log -- path/to/file` |
| Search commits | `git log --grep="keyword"` |

## Useful Git Aliases

Add these to your `.gitconfig` for shortcuts:
```bash
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.lg "log --oneline --graph --all"
git config --global alias.last "show HEAD"
```

Then use:
- `git st` instead of `git status`
- `git lg` instead of `git log --oneline --graph --all`
- `git last` instead of `git show HEAD`