ai-recruit-site-template/README.md

# AI Recruitment Site Template

A fully customizable recruitment website template designed for easy deployment and AI agent modification. Built with Node.js, Express, and PostgreSQL with comprehensive environment-based configuration.

## 🎯 Use This Template

This repository is marked as a template. You can create your own recruitment site in minutes!

### Quick Start (3 Steps)

1. **Use this template** - Click "Use this template" on Gitea
2. **Customize** - Edit `.env` file with your company information
3. **Deploy** - Run the automated deployment script

## ✨ Features

### Public Features
- Job listings with search and filters
- Online application system with CV upload
- Contact form
- Fully responsive design
- Dynamic branding and content

### Admin Features
- Dashboard with statistics
- Application management
- CV downloads and viewing
- Job posting management
- First-time admin account creation

### Template Features
- **Environment-based configuration** - All customization via `.env` file
- **Dynamic branding** - Company name, colors, contact info all configurable
- **AI agent friendly** - Clear structure for automated modifications
- **One-click deployment** - Automated Coolify deployment script
- **No hardcoded values** - Everything is configurable

## 🚀 Quick Deployment

### Prerequisites

- Gitea account at git.startanaicompany.com
- Gitea API token
- Coolify API token (for deployment)
- Basic command line knowledge

### Step 1: Create Your Copy

Use Gitea's template feature to create your own copy:

```bash
# Or clone the template manually
git clone https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template.git my-recruit-site
cd my-recruit-site
```

### Step 2: Customize Configuration

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env with your company information
nano .env
```

**Minimum required configuration in `.env`:**

```bash
# Company Information
COMPANY_NAME="Your Recruitment Firm"
COMPANY_TAGLINE="Your Tagline Here"
COMPANY_DESCRIPTION="Your company description"

# Branding Colors
PRIMARY_COLOR=#2563EB
ACCENT_COLOR=#059669
DARK_COLOR=#1E293B

# Contact Information
CONTACT_EMAIL=info@yourcompany.com
CONTACT_PHONE=+1 (555) 123-4567
CONTACT_ADDRESS=123 Business St, City, State 12345

# Deployment Configuration
SUBDOMAIN=yourname
GITEA_USERNAME=your-gitea-username
GITEA_REPO_NAME=my-recruit-site
```

### Step 3: Deploy to Coolify

```bash
# Set API tokens as environment variables (NOT in .env)
export COOLIFY_API_TOKEN="your-coolify-token"
export GITEA_API_TOKEN="your-gitea-token"

# Copy and run the deployment script
cp deploy-to-coolify.example.sh deploy-to-coolify.sh
chmod +x deploy-to-coolify.sh
./deploy-to-coolify.sh
```

The script will:
- Create a Coolify application
- Configure domain (yourname.recruitai.startanaicompany.com)
- Set up webhooks for automatic deployments
- Generate database and session secrets
- Trigger initial deployment

**Your site will be live in 2-3 minutes!**

## 🎨 Customization Guide

### Company Information

All company information is configured via environment variables in `.env`:

```bash
# Company Identity
COMPANY_NAME="Your Recruitment Firm"
COMPANY_TAGLINE="Finding the Perfect Match for Your Career"
COMPANY_DESCRIPTION="We specialize in connecting talented professionals..."

# Contact Details
CONTACT_EMAIL=info@yourcompany.com
CONTACT_PHONE=+1 (555) 123-4567
CONTACT_ADDRESS=123 Business St, Suite 100, City, State 12345
BUSINESS_HOURS=Monday - Friday: 9:00 AM - 6:00 PM

# Social Media (leave empty to hide)
SOCIAL_LINKEDIN=https://linkedin.com/company/yourcompany
SOCIAL_TWITTER=https://twitter.com/yourcompany
SOCIAL_FACEBOOK=
```

### Branding Colors

Customize your brand colors:

```bash
PRIMARY_COLOR=#2563EB  # Main brand color (buttons, links)
ACCENT_COLOR=#059669   # Success/accent color
DARK_COLOR=#1E293B     # Dark elements (footer, headings)
```

Colors update automatically across the entire site!

### About Page Content

```bash
ABOUT_MISSION=Our mission statement here
ABOUT_VISION=Our vision statement here
ABOUT_VALUES=Integrity, Excellence, Innovation, Partnership
```

### Services Offered

```bash
SERVICES_LIST=Executive Search,Contract Staffing,Permanent Placement,Career Consulting
```

### Feature Configuration

```bash
MAX_CV_SIZE_MB=5
ALLOWED_CV_TYPES=application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document
```

## 🤖 AI Agent Modification

This template is designed to be easily modified by AI agents like Claude Code. The structure includes:

### Clear File Organization

```
ai-recruit-site-template/
├── config.js              # Centralized configuration
├── server.js              # Main application
├── public/
│   ├── js/
│   │   └── init.js       # Dynamic config injection
│   ├── css/
│   │   └── styles.css    # CSS with variables
│   └── *.html            # HTML with data attributes
├── migrations/            # Database migrations
└── .env.example          # Configuration template
```

### Data Attributes

HTML elements use data attributes for dynamic content:

```html
<div data-company-name>Your Company</div>
<h1 data-company-tagline>Your Tagline</h1>
<a data-contact-email>email@example.com</a>
```

### Configuration API

Frontend can access configuration via API:

```javascript
// GET /api/config returns:
{
  company: { name, tagline, description },
  branding: { primaryColor, accentColor, darkColor },
  contact: { email, phone, address, businessHours },
  social: { linkedin, twitter, facebook },
  about: { mission, vision, values },
  services: { list: [...] }
}
```

## 💻 Local Development

### With Docker (Recommended)

```bash
cp .env.example .env
# Edit .env with your settings

docker-compose up -d
```

Access at: http://localhost:3000

### Without Docker

```bash
# Install dependencies
npm install

# Start PostgreSQL (must be running)
# Create database 'recruitment'

# Copy environment file
cp .env.example .env

# Start application
npm start
```

## 📊 Technology Stack

- **Backend**: Node.js 18 + Express
- **Database**: PostgreSQL 15 with BYTEA for CV storage
- **Authentication**: Session-based with bcrypt
- **File Upload**: Multer (PDF, DOC, DOCX)
- **Deployment**: Docker Compose + Coolify
- **DNS**: Cloudflare

## 🔐 Security Features

- Password hashing with bcrypt (10 rounds)
- Secure HTTP-only session cookies
- SQL injection protection (parameterized queries)
- File upload validation (type and size)
- Environment-based secrets
- Automatic HTTPS in production

## 📚 API Documentation

### Public APIs

- `GET /api/config` - Get site configuration
- `GET /api/jobs` - List active jobs
- `GET /api/jobs/:id` - Get job details
- `POST /api/apply` - Submit application (multipart/form-data)
- `POST /api/contact` - Submit contact form

### Admin APIs (Authentication Required)

- `POST /api/admin/login` - Login / Create first admin
- `GET /api/admin/check` - Check auth status
- `POST /api/admin/logout` - Logout
- `GET /api/admin/stats` - Dashboard statistics
- `GET /api/admin/applications` - List applications (with filters)
- `GET /api/admin/applications/:id` - Get application details
- `GET /api/admin/applications/:id/cv` - Download CV
- `PATCH /api/admin/applications/:id` - Update application status
- `GET /api/admin/jobs` - List all jobs
- `POST /api/admin/jobs` - Create job
- `PATCH /api/admin/jobs/:id` - Update job (activate/deactivate)

## 🆘 Troubleshooting

### Deployment Issues

```bash
# Check Coolify logs
# Visit: https://app.coolify.io → Your Application → Logs

# Re-trigger deployment
curl -X POST "https://app.coolify.io/api/v1/applications/YOUR_APP_UUID/restart" \
  -H "Authorization: Bearer $COOLIFY_API_TOKEN"
```

### Database Issues

```bash
# Check database connection
docker-compose logs postgres

# Access database
docker-compose exec postgres psql -U postgres -d recruitment

# List tables
\dt
```

### Configuration Not Updating

Make sure you:
1. Updated `.env` file
2. Committed and pushed changes (triggers webhook)
3. Waited 2-3 minutes for redeployment

## 🎓 First Time Setup

1. Visit your deployment URL
2. Go to `/admin/login`
3. System detects no admin exists
4. Fill in email, password, and full name
5. Click "Create Admin Account"
6. You're logged in!

## 📝 Environment Variables Reference

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `COMPANY_NAME` | Your company name | Your Recruitment Firm | Yes |
| `COMPANY_TAGLINE` | Main tagline | Finding the Perfect Match... | Yes |
| `COMPANY_DESCRIPTION` | Company description | We specialize in... | Yes |
| `PRIMARY_COLOR` | Primary brand color | #2563EB | No |
| `ACCENT_COLOR` | Accent color | #059669 | No |
| `DARK_COLOR` | Dark color | #1E293B | No |
| `CONTACT_EMAIL` | Contact email | info@yourcompany.com | Yes |
| `CONTACT_PHONE` | Contact phone | +1 (555) 123-4567 | Yes |
| `CONTACT_ADDRESS` | Physical address | 123 Business St... | Yes |
| `BUSINESS_HOURS` | Business hours | Monday - Friday... | No |
| `SOCIAL_LINKEDIN` | LinkedIn URL | (empty) | No |
| `SOCIAL_TWITTER` | Twitter URL | (empty) | No |
| `SOCIAL_FACEBOOK` | Facebook URL | (empty) | No |
| `SUBDOMAIN` | Your subdomain | yourname | Yes (deploy) |
| `GITEA_USERNAME` | Your Gitea username | - | Yes (deploy) |
| `GITEA_REPO_NAME` | Your repo name | - | Yes (deploy) |
| `DB_PASSWORD` | Database password | (auto-generated) | No |
| `SESSION_SECRET` | Session secret | (auto-generated) | No |
| `MAX_CV_SIZE_MB` | Max CV file size | 5 | No |
| `ALLOWED_CV_TYPES` | Allowed CV MIME types | pdf,doc,docx | No |

## 🤝 Contributing

This is a template repository. Feel free to:
- Fork it for your own recruitment site
- Customize it to your needs
- Submit improvements via pull request

## 📄 License

MIT License - feel free to use for commercial projects

## 🆘 Support

For issues or questions:
- Check the [How to set up a template repo guide](/home/milko/projects/airepotemplates/How-to-set-up-a-template-repo.md)
- Contact: info@startanaicompany.com