finlion-website/cline_docs/gitWorkflow.md

# Git Workflow & Memory Bank

## Git Configuration

### Repository Information
- **Repository URL**: `https://gitea.sigd.net/chaulmark/finlion-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/Writing_Project/FinLion`
- **Main Branch**: `main`
- **Latest Commit**: `3fb2204c6f5ca9f8769dc56c1a00079a795e19c2`

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

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

### Git User Configuration
```bash
user.name=eliza
user.email=eliza@gitea.sigd.net
```

## 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/app/page.tsx

# Commit changes with meaningful message
git commit -m "Update homepage: Add new hero section"

# 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/app/page.tsx

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

# Who changed what in a file
git blame src/app/page.tsx
```

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

# Unstage a file (keep changes)
git reset HEAD src/app/page.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
```

## 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/finlion-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 an email address)

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

## FinLion Website Codebase Overview

### Project Architecture

```
FinLion/
├── Next.js Application (React + TypeScript)
│   ├── src/
│   │   ├── app/            # Next.js App Router pages
│   │   │   ├── page.tsx    # Homepage
│   │   │   ├── layout.tsx  # Root layout
│   │   │   ├── about/      # About page
│   │   │   ├── services/   # Services page
│   │   │   ├── contact/    # Contact page
│   │   │   └── api/        # API routes
│   │   ├── components/     # React components
│   │   │   ├── home/       # Home-specific components
│   │   │   ├── layout/     # Layout components
│   │   │   ├── shared/     # Shared components
│   │   │   └── ui/         # UI components
│   │   ├── data/           # Data files
│   │   ├── lib/            # Utility functions
│   │   ├── styles/         # Global styles
│   │   └── types/          # TypeScript types
│   └── public/             # Static assets
│       └── images/         # Image files
│
├── Docker Configuration
│   ├── docker-compose.yml        # Production orchestration
│   ├── docker-compose.dev.yml    # Development environment
│   ├── Dockerfile                # Production container
│   └── Dockerfile.dev            # Development container
│
├── Documentation
│   └── cline_docs/               # AI assistant documentation
│       ├── memoryBank.md         # This memory bank
│       └── gitWorkflow.md        # Git workflow guide
│
└── Configuration Files
    ├── next.config.ts            # Next.js configuration
    ├── tailwind.config.ts        # Tailwind CSS config
    ├── tsconfig.json             # TypeScript config
    ├── package.json              # Dependencies
    ├── pnpm-lock.yaml            # Lock file
    └── .env                      # Environment variables (SECRET)
```

### Key Files and Their Purposes

#### Application Pages (`src/app/`)
- **page.tsx**: Homepage/landing page with hero and overview
- **layout.tsx**: Root layout component (affects all pages)
- **about/page.tsx**: About page
- **services/page.tsx**: Services showcase page
- **contact/page.tsx**: Contact form page
- **api/contact/route.ts**: Contact form submission API endpoint

#### Components (`src/components/`)
- **layout/**: Header, Navigation, Footer
- **home/**: Hero, Services sections for homepage
- **shared/**: Toast notification component
- **ui/**: Reusable UI components like Button
- **Modal.tsx**: Modal dialog component
- **ServiceCard.tsx**: Service display cards

#### Data & Utilities
- **src/data/services.ts**: Services data structure
- **src/lib/email.ts**: Email service integration
- **src/lib/rate-limit.ts**: Rate limiting logic for API
- **src/types/services.ts**: TypeScript type definitions

### Important Patterns

#### 1. Next.js App Router Structure
```
src/app/
├── page.tsx              # Homepage (/)
├── layout.tsx            # Root layout
├── about/
│   └── page.tsx         # About page (/about)
├── services/
│   └── page.tsx         # Services page (/services)
├── contact/
│   └── page.tsx         # Contact page (/contact)
└── api/
    └── contact/
        └── route.ts     # API endpoint (/api/contact)
```

#### 2. Environment Variables
Critical `.env` variables:
```env
# Email Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=gmail_app_password
FROM_EMAIL=your-from-email
TO_EMAIL=your-to-email

# Redis Configuration (for rate limiting)
UPSTASH_REDIS_REST_URL=your-redis-url
UPSTASH_REDIS_REST_TOKEN=your-redis-token
```

#### 3. Services Data Structure
```typescript
// src/data/services.ts
export const services = [
  {
    id: 'service-id',
    title: 'Service Title',
    description: 'Service description',
    icon: IconComponent,
    features: ['Feature 1', 'Feature 2']
  }
]
```

### 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` (runs on http://localhost:3000)

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
   ```

#### Updating Page Content

1. **Identify the correct file:**
   - Homepage: `src/app/page.tsx` or `src/components/home/Hero.tsx`
   - About: `src/app/about/page.tsx`
   - Services: `src/app/services/page.tsx` or `src/data/services.ts`
   - Contact: `src/app/contact/page.tsx`

2. **Edit the content**

3. **Test locally:**
   ```bash
   pnpm dev
   # Visit http://localhost:3000 to verify changes
   ```

4. **Commit and push:**
   ```bash
   git add src/app/
   git commit -m "Update [page]: [description]"
   git push
   ```

#### Adding New Service

1. **Edit services data:**
   - File: `src/data/services.ts`
   - Add new service object to array

2. **Update services page if needed:**
   - File: `src/app/services/page.tsx`

3. **Test and commit:**
   ```bash
   git add src/data/services.ts src/app/services/
   git commit -m "Add new service: [Service Name]"
   git push
   ```

#### Updating Styling

1. **Identify component:**
   - Components use Tailwind CSS classes
   - Global styles in `src/styles/globals.css`

2. **Update Tailwind classes or CSS**

3. **Test and commit:**
   ```bash
   git add src/
   git commit -m "Update styling: [description]"
   git push
   ```

### Local Development Commands

#### Development Server
```bash
# Install dependencies (first time only)
pnpm install

# Start development server
pnpm dev
# Opens at http://localhost:3000

# Build for production
pnpm build

# Start production server
pnpm start

# Run linting
pnpm lint
```

#### Docker Development
```bash
# Start development with Docker
docker compose -f docker-compose.dev.yml up

# Start production with Docker
docker compose up --build -d

# View logs
docker logs [container-name]

# Stop containers
docker compose down
```

### 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="homepage"

# Find commits that changed a specific file
git log -- src/app/page.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:
  - ✅ "Update homepage hero section with new tagline"
  - ✅ "Fix contact form validation and email sending"
  - ✅ "Add new financial planning service to services page"
  - ❌ "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 with `pnpm dev` if possible
2. Review changes with `git status` and `git diff`
3. Commit with clear message
4. Push to remote

### Working with Next.js
- Test changes locally before pushing
- Verify responsive design on different screen sizes
- Check console for errors in browser
- Test contact form if email changes made
- 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"` |
| Start dev server | `pnpm dev` |
| Build for production | `pnpm build` |

## 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`

## Recent History (Reference Only)

### Setup (March 13, 2026)
- Cloned repository from Gitea
- Configured Git authentication with Eliza's credentials
- Set up user configuration (eliza / eliza@gitea.sigd.net)
- Created memory bank and git workflow documentation
- Repository status: Working tree clean, up to date with origin/main