ScoutSSD

An autonomous scholarship discovery and application pipeline.

ScoutSSD scrapes scholarship sources, evaluates eligibility, generates tailored application essays using your personal voice profile, and manages the submission pipeline — with human-in-the-loop review via a web dashboard and Discord notifications.

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   Scraper   │───▶│  Supervisor  │───▶│  Dashboard  │
│  (sources)  │    │  (pipeline)  │    │  (Next.js)  │
└─────────────┘    └──────┬───────┘    └─────────────┘
                          │
               ┌──────────▼──────────┐
               │    Essay Engine     │
               │   (LLM + voice)    │
               └──────────┬──────────┘
                          │
               ┌──────────▼──────────┐   ┌─────────────┐
               │    Submitter        │──▶│  Discord    │
               │  (browser-use)     │   │    Bot      │
               └─────────────────────┘   └─────────────┘

Stack: Python (FastAPI) + Node.js (Next.js 14) + PostgreSQL (Docker) + Obsidian vault (profile/essays)

Features

• Multi-source scholarship scraping — configurable JSON source definitions with automatic pagination and deduplication
• Eligibility qualification — rule-based filtering using your profile data
• AI essay generation — Gemini/OpenRouter-powered essay writing with voice profile matching and anti-AI-detection post-processing
• Browser-use form submission — automated form filling via Playwright with human review gates
• Discord review workflow — approve/deny/skip scholarships directly from Discord with slash commands
• Web dashboard — real-time pipeline status, preparation queue, and submission tracking
• Safe mode & build mode — configurable safety gates prevent accidental submissions
• Windows + WSL2 support — runs on Windows with WSL2 for Linux services

Quick Start

Prerequisites

• Docker Desktop (with WSL2 backend on Windows)
• Node.js 18+
• Python 3.11+
• Obsidian (optional, for profile/essay management)

Setup

1. Clone and configure:

git clone https://github.com/YOUR_USERNAME/ScoutSSD.git
cd ScoutSSD
cp .env.example .env
# Edit .env with your real values — see .env.example for instructions

2. Set up your profile:

cp obsidian-vault/00-Profile/profile-template.md obsidian-vault/00-Profile/profile-summary.md
# Fill in your real data in profile-summary.md (it's gitignored)

3. Start services:

docker compose up -d
./scripts/setup.sh

4. Access the dashboard: http://localhost:3001

See QUICKSTART.md for detailed setup instructions.

Configuration

All configuration is via environment variables. Copy .env.example to .env and fill in your values.

Key variables:

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
GEMINI_API_KEY	Google Gemini API key	Yes
DISCORD_BOT_TOKEN	Discord bot token (for review notifications)	Optional
SCOUTSCHOLAR_BUILD_MODE	Enable build mode (no real submissions)	Recommended
SCOUTSCHOLAR_SAFE_MODE	Enable safety gates	Recommended

Project Structure

ScoutSSD/
├── browser-use/        # Python FastAPI service (scraper, supervisor, essay engine, submitter)
│   ├── main.py         # API endpoints and startup
│   ├── supervisor.py   # Pipeline orchestrator
│   ├── essay_engine.py # AI essay generation
│   ├── discord_bot.py  # Discord review notifications
│   └── tests/          # Python test suite
├── dashboard/          # Next.js 14 web dashboard
│   └── src/            # React components and pages
├── db/                 # Database schema and migrations
│   └── init.sql        # Full PostgreSQL schema
├── scripts/            # Startup, setup, and utility scripts
├── source_configs/     # JSON scholarship source definitions
├── obsidian-vault/     # Profile, essays, and voice profile (templates committed, real data gitignored)
├── infra/              # Systemd services and Windows WSL scripts
└── docs/               # Documentation

Development

# Run Python tests
cd browser-use && python -m pytest tests/ -v

# Run dashboard tests
cd dashboard && npm test

# Start in development mode
docker compose up -d
./scripts/start-all.sh

Safety

ScoutSSD has multiple safety mechanisms to prevent unintended scholarship submissions:

• Build Mode (SCOUTSCHOLAR_BUILD_MODE=true) — prevents any real submissions
• Safe Mode (SCOUTSCHOLAR_SAFE_MODE=true) — adds confirmation gates
• Auto-submit disabled by default — requires explicit AUTO_SUBMIT_ENABLED=true
• Final submit disabled by default — requires SCOUTSCHOLAR_FINAL_SUBMIT_ENABLED=true
• Discord review workflow — human approval required before submission

License

MIT

Contributing

See CONTRIBUTING.md for guidelines. See SECURITY.md for reporting vulnerabilities.