#Hackathon Launch & Marketing Agent

Production-oriented MVP for a multi-agent hackathon launch system. It takes a hackathon brief and generates a launch-ready package with research, branding, landing page copy, outreach emails, sponsor pitch outline, social campaign, operations timeline, budget, risks, and critic review.

Architecture Summary

• Frontend: Next.js pages for dashboard, event creation, live agent monitor, package editing, memory search, no-token message generation, analytics, settings, and Clerk auth.
• Backend: FastAPI with async SQLAlchemy, PostgreSQL persistence, Alembic migrations, Clerk JWT verification, WebSocket progress updates, structured Pydantic contracts, and background workflow execution.
• Prompts: every agent's system instruction and user prompt lives in a versioned file under backend/app/prompts/, editable through /prompts and the console's prompt studio, with a live preview that uses the same renderer as the pipeline. Set PROMPT_TEMPLATES_DIR to relocate them and PROMPT_EDITING_ENABLED=false to make them read-only in production.
• Agents: Orchestrator coordinates Research, Branding, Content, Social Media, Operations, and Critic agents. Each agent has narrow inputs/outputs and validated JSON contracts. AGENT_RUNTIME=gemini uses Gemini when a Google key is configured and deterministic fallback when no key is present.
• Memory: Qdrant collections for long-term memory, bootstrapped idempotently (create what is missing, verify what exists, refuse to silently drop a collection whose vector size does not match EMBEDDING_DIM), with a labelled in-process fallback and a parity self-test that checks the fallback answers the same questions the same way.
• Tooling: MCP servers expose Qdrant memory tools and safe utility tools.
• Deployment: Docker Compose starts Postgres, Qdrant, FastAPI, Next.js, and MCP services.

Folder Structure

hackathon-agent/
  backend/
    alembic/
    app/
      api/
      core/
      db/
      models/
      services/
      tasks/
      main.py
      ws.py
  frontend/
    components/
    pages/
    services/
    store/
    styles/
  mcp-servers/
    qdrant-mcp/
    tools-mcp/
  docs/
  docker-compose.yml
  docker-compose.prod.yml
  .env.example

Database Schema

Core tables are implemented in backend/app/db/models.py:

• users: local user records, password hash scaffold, preferences.
• projects: user-owned launch workspaces.
• events: event brief, status, final package, venue/date, error field.
• campaigns: generated launch/social campaigns.
• assets: landing page copy, pitch outlines, social plans, and future artifacts.
• tasks: operational tasks generated by the Operations agent.
• agent_runs: every agent invocation with structured input/output, status, runtime, timestamps, and errors.
• audit_logs: append-only run and workflow logs.
• memory_records: optional relational index of memory writes.

Agent Contracts

Contracts live in backend/app/models/agent.py.

• Research: trends, audience insights, competitors, sponsor targets, risks, memory used.
• Branding: name options, selected name, tagline, palette, tone, typography, logo concepts.
• Content: landing page, outreach emails, sponsor pitch outline, FAQ, judging rubric, risk narrative.
• Social Media: four-week campaign, channel-specific posts, hashtags, cadence.
• Operations: timeline, tasks, staffing plan, budget lines, logistics, mitigations.
• Critic: scores, issues, suggestions, approval, refinement flag.
• LaunchPackage: compiled final package plus markdown artifact.

API Contracts

• POST /events/launch: create an event and queue the workflow.
• GET /events/{id}/status: event status and inferred progress.
• GET /events/{id}/output: final launch package when ready.
• PATCH /events/{id}/output: persist edited package markdown or fields.
• GET /events/{id}: event record.
• GET /projects: projects with events.
• GET /agents/{run_id}/output: one agent run.
• GET /agents?event_id={id}: recent runs.
• GET /memory/search?query=...: Qdrant/fallback memory search.
• GET /memory/status: which backend memory is really on, per collection, with record counts and the last bootstrap report.
• GET /memory/points?collection=: raw stored records, for the inspector panel.
• POST /memory/bootstrap: re-run the idempotent collection bootstrap.
• POST /memory/parity: run the fallback parity self-test.
• GET /analytics/overview: dashboard metrics.
• POST /auth/register: optional local JWT registration for API demos.
• POST /auth/login: optional local JWT login for API demos.
• GET /auth/session: authenticated Clerk/local session inspection.
• GET /prompts: list agent prompt templates with metadata.
• GET /prompts/{name}: one template, including system and user text.
• POST /prompts/{name}/preview: render a template (or unsaved editor content) against variables, reporting missing and unused placeholders.
• PUT /prompts/{name}: save a new version, archiving the previous one.
• GET /prompts/{name}/versions, POST /prompts/{name}/revert/{version}.
• GET /events/{id}/progress?since=: buffered progress frames (REST twin of the WebSocket replay).
• GET /health: liveness. Answers from process state only, always 200 while the process is serving. This is the path Render's health check uses, so a degraded Qdrant can never cause a restart loop.
• GET /health?deep=true (alias GET /health/ready): readiness. Probes every dependency with a bounded timeout and returns a HealthReport — overall status (ok / degraded / starting / down), uptime, auth mode, effective agent runtime, and a dependencies[] entry per dependency with its own status, latency, human-readable detail, and the fallback carrying the load when one is. Returns 503 only when a required dependency is down or startup has not completed.
• WS /ws/{event_id}: live agent progress events.

Implementation Plan

1. MVP: deterministic local multi-agent workflow, persistence, WebSocket progress, editable package UI.
2. Extended MVP: enable Qdrant, RAG ingest, richer memory tools, Gemini-backed generation, stronger review loop.
3. Production hardening: strict auth, rate limits, prompt-injection defenses, observability, CI/CD, and optional A2A service split.

Run Locally

docker compose up --build

Then open:

• Frontend: http://localhost:3000
• Backend docs: http://localhost:8000/docs

The default runtime is gemini: it uses Gemini-backed generation when GEMINI_API_KEY or GOOGLE_API_KEY is configured, and falls back to deterministic generation when no key exists. This keeps demos token-safe while making the Google integration active by default in configured environments.

Clerk authentication is wired into the frontend at /sign-in and /sign-up. The frontend forwards Clerk session tokens to the backend, and FastAPI can verify them with CLERK_ISSUER_URL or CLERK_JWKS_URL. Use BACKEND_AUTH_MODE=optional for local demos and BACKEND_AUTH_MODE=strict for production.

Production database migrations are included and can run automatically with RUN_MIGRATIONS_ON_STARTUP=true:

cd backend
alembic upgrade head

See docs/judging-readiness.md for the scoring-focused implementation notes and docs/security.md for the production security checklist. GitHub Actions CI is included in .github/workflows/ci.yml.

Frontend dependencies are locked with pnpm. For local frontend-only checks:

cd frontend
pnpm install
pnpm lint
pnpm build