BrandPilot

BrandPilot is a production-oriented full-stack implementation of the master plan:

• Parallel marketing agent fleet (Competitor, Reviews, Mentions, Opportunities)
• Intelligence compiler digest
• Single command-center UI with clear multi-section workflow
• Cloud-ready storage, notifications, and scheduled execution

Hackathon submission pack

• Final pack: docs/hackathon_submission_pack.md
• Judge script: docs/judge_demo_script.md
• Live runbook: docs/demo_runbook_live.md

Current deployed environment note:

• Production deployment runs AgentMode=live with Nova Act + AgentCore Browser in Lambda.
• Bedrock digest generation, S3 persistence, scheduler, and SNS delivery are live.
• UI runtime badge shows per-run execution source (Live, Fallback, Mixed, Mock) from backend telemetry.

Implemented scope

Backend

• FastAPI API (/health, /api/system/status, /api/onboarding, /api/run, /api/runs, /api/dashboard/{persona}, /api/digest/latest)
• Built-in authentication:
  • Email/password register + login
  • Google login (when GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET are configured)
  • Bearer token auth for all workspace APIs
• Multi-user isolation:
  • Per-user onboarding, runs, dashboards, strategy, timeline, and integrations data
  • User-scoped S3/local storage namespaces
• Parallel agent orchestration with execution modes:
  • mock: deterministic demo data
  • hybrid: try Nova Act, fallback to mock on failure
  • live: only live Nova Act (captures errors in runtime metadata)
• Digest pipeline:
  • Rule-based digest always available
  • Optional Bedrock Nova 2 Lite digest (converse) with safe fallback
• Storage adapters:
  • Local filesystem
  • S3 bucket
• Optional SNS publishing of digest
• Local interval scheduler hook
• AWS Lambda handlers:
  • app.lambda_handler.handler for scheduled runs
  • app.lambda_api.handler for serverless API via Mangum

Frontend

• React + TypeScript dashboard
• Unified command-center layout with guided sections
• Onboarding form and one-click fleet run
• Digest + signal cards
• Run timeline and execution telemetry
• Runtime indicators (mode, digest engine, SNS delivery status)

Infra

• SAM template (infra/template.yaml) provisioning:
  • S3 results bucket
  • SNS digest topic
  • HTTP API container Lambda (Mangum/FastAPI)
  • Scheduled container Lambda run with IAM for S3/SNS/Bedrock and Nova Act runtime dependencies
• Deployment helper script (infra/deploy.ps1)

Project structure

• backend/ FastAPI services, agents, tests, Lambda handlers
• frontend/ Vite React app
• infra/ SAM template and deployment script

Local development

1) Backend

cd backend
python -m venv .venv
. .venv/Scripts/activate
pip install -r requirements.txt
copy .env.example .env
uvicorn app.main:app --reload --port 8000

Optional live Nova Act dependency:

pip install -r requirements-optional.txt

2) Frontend

cd frontend
npm install
copy .env.example .env
npm run dev

If backend API_KEY is set, also set VITE_API_KEY in frontend/.env.

• Frontend: http://localhost:5173
• Backend: http://localhost:8000

Docker

docker compose up --build

• Frontend: http://localhost:8080
• Backend: http://localhost:8000

Backend environment variables

Use backend/.env.example as reference.

Core:

• APP_VERSION=1.1.0
• API_KEY=<optional; when set, required via X-API-Key for POST endpoints>
• AUTH_TOKEN_SECRET=<required in production>
• AUTH_TOKEN_TTL_HOURS=168
• STORAGE_BACKEND=local|s3
• S3_BUCKET=<bucket-name> when s3
• AWS_REGION=us-east-1
• AWS_PROFILE=<optional-profile>

Agent runtime:

• AGENT_MODE=mock|hybrid|live
• NOVA_ACT_API_KEY=<required for live Nova Act>
• NOVA_ACT_MAX_LINKS=3
• NOVA_ACT_HEADLESS=1 (recommended in Lambda/container runtimes)
• NOVA_ACT_CHROME_CHANNEL=chromium (recommended in Lambda/container runtimes)
• NOVA_ACT_BROWSER_ARGS=--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage --disable-gpu (recommended in Lambda/container runtimes)
• USE_MOCK_DATA=true|false (legacy compatibility)

Digest intelligence:

• BEDROCK_ENABLED=true|false
• BEDROCK_MODEL_ID=us.amazon.nova-2-lite-v1:0
• BEDROCK_TEMPERATURE=0.2
• BEDROCK_MAX_TOKENS=700

Notifications:

• SNS_ENABLED=true|false
• SNS_TOPIC_ARN=<topic-arn>
• SNS_MESSAGE_SUBJECT=BrandPilot Weekly Digest

Scheduler:

• SCHEDULER_ENABLED=true|false
• SCHEDULER_INTERVAL_MINUTES=10080

OAuth integrations:

• FRONTEND_BASE_URL=<frontend public URL used for OAuth callback redirects>
• OAUTH_STATE_SECRET=<required non-empty secret for signing OAuth state>
• GOOGLE_CLIENT_ID=<optional>
• GOOGLE_CLIENT_SECRET=<optional>
• META_CLIENT_ID=<optional>
• META_CLIENT_SECRET=<optional>
• LINKEDIN_CLIENT_ID=<optional>
• LINKEDIN_CLIENT_SECRET=<optional>
• X_CLIENT_ID=<optional>
• X_CLIENT_SECRET=<optional>

OAuth callback paths (configure these in each provider console):

• Google: <API_URL>/api/integrations/oauth/google/callback
• Meta: <API_URL>/api/integrations/oauth/meta/callback
• LinkedIn: <API_URL>/api/integrations/oauth/linkedin/callback
• X: <API_URL>/api/integrations/oauth/x/callback

Hackathon demo note:

• OAuth is optional for judging and can remain unconfigured for demo runs.
• The UI already shows provider connection controls and configuration state.
• For demo narration: "OAuth connectors are production-ready in code and activate once provider credentials are supplied."

Serverless deployment (AWS SAM)

Prerequisites:

• AWS CLI + SAM CLI configured
• Python 3.12 runtime target

Deploy:

./infra/deploy.ps1 -StackName brandpilot-prod -Region us-east-1 -AgentMode live -NovaActApiKey <your_nova_key> -ApiKey <optional_api_key>

AgentMode=live enables Nova Act execution for both manual API runs and scheduled runs.

For browser access from deployed frontend, pass allowed origins:

./infra/deploy.ps1 -StackName brandpilot-prod -Region us-east-1 -AgentMode mock -CorsOrigins "http://localhost:5173,http://brandpilot-web-<account>-us-east-1.s3-website-us-east-1.amazonaws.com"

Finalize (without full image rebuild) after you have a valid Nova key:

./infra/finalize.ps1 -StackName brandpilot-prod -Region us-east-1 -NovaActApiKey <your_nova_key> -AgentMode live -NotificationEmail <your_email>

Configure real OAuth credentials in the deployed stack:

./infra/finalize.ps1 \
  -StackName brandpilot-prod \
  -Region us-east-1 \
  -NovaActApiKey <your_nova_key> \
  -AgentMode live \
  -OauthStateSecret <long_random_secret> \
  -GoogleClientId <google_client_id> \
  -GoogleClientSecret <google_client_secret> \
  -MetaClientId <meta_client_id> \
  -MetaClientSecret <meta_client_secret> \
  -LinkedinClientId <linkedin_client_id> \
  -LinkedinClientSecret <linkedin_client_secret> \
  -XClientId <x_client_id> \
  -XClientSecret <x_client_secret>

After this, connect providers from the Channels section in the app and verify /api/system/status shows oauth_providers_configured=true for providers you set.

Run a deployment verification and generate a report:

./infra/verify.ps1 -StackName brandpilot-prod -Region us-east-1 -ApiUrl https://givev7ga9i.execute-api.us-east-1.amazonaws.com

Template file: infra/template.yaml

Default schedule expression in template: cron(0 8 ? * MON *).

The scheduler function is image-based and deployed with --resolve-image-repos.

Frontend deployment (public web URL)

Deploy the React frontend to an S3 static website bucket wired to the live API:

./infra/deploy_frontend.ps1 -StackName brandpilot-prod -Region us-east-1

The script will:

• Resolve API URL from CloudFormation outputs
• Build frontend with VITE_API_BASE_URL pointing to deployed API
• Configure S3 static website hosting and upload build artifacts
• Print the public website URL

Enable SNS email delivery

SNS publish is live after deployment, but email delivery requires at least one subscription:

aws sns subscribe \
  --topic-arn <DigestTopicArn output> \
  --protocol email \
  --notification-endpoint <your-email>

Then confirm the subscription from the inbox confirmation email.

API endpoints

• GET /health
• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/me
• GET /api/auth/google/start
• GET /api/auth/google/callback
• GET /api/system/status
• GET /api/onboarding
• POST /api/onboarding
• POST /api/run
• GET /api/runs
• GET /api/dashboard/{persona}
• GET /api/digest/latest
• GET /api/strategy/latest
• GET /api/timeline
• POST /api/timeline
• POST /api/timeline/item
• PATCH /api/timeline/{item_id}
• GET /api/integrations
• GET /api/integrations/oauth/{provider}/start
• GET /api/integrations/oauth/{provider}/callback
• POST /api/integrations/{provider}/disconnect

Tests and build

Backend:

cd backend
pytest

Frontend:

cd frontend
npm run build

Hackathon delivery checklist status in codebase

Implemented in code:

• Multi-agent fleet execution
• Persona dashboards
• Parallel orchestration
• S3-compatible results persistence
• Bedrock digest integration path
• SNS digest publish path
• Scheduler integration path
• Verification script + readiness report generation (infra/verify.ps1)
• Demo runbook (docs/hackathon_runbook.md)

Still manual (outside code):

• YouTube demo recording/upload
• Devpost submission form completion
• Blog post publishing and link submission