Role2 Builder

Role2 Builder is a Next.js frontend (deployed on Vercel at www.role2builder.org) backed by a FastAPI service (backend/) reachable at https://api.role2builder.org.

Getting Started (frontend)

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying app/page.tsx. The page auto-updates as you edit the file.

This project uses next/font to automatically optimize and load Geist, a new font family for Vercel.

Deployment Architecture

Updated 2026-07-25: the backend no longer runs in its own AWS environment. The dedicated Elastic Beanstalk environment role2-builder-prod was terminated for cost consolidation.

Backend (FastAPI)

The FastAPI backend now runs as a second Docker Compose service on the R2RA production instance (Elastic Beanstalk environment r2ra-prod, AWS account 885232248320, us-east-1), listening on port 8080 of that instance.

Public entry is unchanged: https://api.role2builder.org is a CloudFront distribution whose origin now points to r2ra-prod.eba-yg3nk3rp.us-east-1.elasticbeanstalk.com:8080.

Frontend (Next.js)

The Next.js frontend on Vercel (www.role2builder.org) is unaffected by this change.

CI/CD: the pipeline publishes, it does not deploy

The role2-builder CodePipeline no longer deploys anything. Its final stage uploads the built bundle (Dockerfile, backend/, requirements.txt) to:

s3://r2ra-artifacts-885232248320/role2-builder/latest.zip

The R2RA repo's build pulls that bundle into its own deploy artifact — see R2RA's buildspec.yml and deploy/docker-compose.eb.yml.

Shipping a backend change (fully automatic)

A push to main (excluding docs/markdown-only changes) deploys with no manual steps:

1. GitHub Actions (.github/workflows/deploy.yml) authenticates to AWS through GitHub OIDC (IAM role github-actions-start-pipeline — no AWS keys stored in GitHub) and starts the role2-builder pipeline, which publishes the bundle to S3.
2. When that pipeline succeeds, the EventBridge rule rb-publish-chains-r2ra automatically starts the r2ra pipeline, which pulls the bundle and deploys to r2ra-prod. Live ~15 minutes after the push.

Ordering only matters if you bypass the automation — a manually started r2ra run must wait for the role2-builder pipeline to finish first, or the deploy ships the previous (stale) bundle.

Manual fallback if the workflow is unavailable (run in order, waiting for the first to finish):

aws codepipeline start-pipeline-execution --name role2-builder
aws codepipeline start-pipeline-execution --name r2ra

Dockerfile / build bundle

The Dockerfile builds the FastAPI backend image consumed by the R2RA deploy. The buildspec.yml artifact selection (Dockerfile, backend/, requirements.txt) defines the exact bundle shape the R2RA deploy consumes.

⚠️ Runtime contract — do not break these:

• The container must keep serving on port 8000 internally — the R2RA compose file maps 8080 → 8000.
• The container receives only CORS_ORIGINS and GEMINI_API_KEY as environment variables. They are set on the r2ra-prod EB environment, not in this repo.
• The container must not assume a DATABASE_URL. Saved exercises (the /history page) live in a private S3 bucket instead, via backend/archive.py: role2-exercises-885232248320 (us-east-1; one gzipped JSON per exercise plus index.json; ~7 MB, well under a cent a month, nothing always-on). The bucket name is a code default (override with EXERCISE_BUCKET, empty = off), so no new env var is needed. The r2ra-eb-ec2-role instance role carries an inline policy, role2-exercises-archive (s3:ListBucket on the bucket, s3:GetObject + s3:PutObject on its objects). Old Railway rows are loaded with python scripts/import_exercises.py exercises.json.
• Gemini cost guards are built in with safe defaults and need no new env vars. They can optionally be tuned on the EB environment: MAX_USD_PER_EXERCISE (default 5), MAX_USD_PER_DAY (25, UTC day, then /generate-exercise returns 429), MAX_CONCURRENT_JOBS (2), MAX_CALLS_PER_CASE (4), and thinking-token caps THINKING_CASE (1024), THINKING_CONTROLLER (2048), THINKING_REVIEW (1024), THINKING_REVISE (512), THINKING_ORDERS (1024). Spend is estimated from token usage at GEMINI_PRICE_IN_PER_M / GEMINI_PRICE_OUT_PER_M (0.30 / 2.50 USD) and logged per exercise (AI usage for ...) — the in-process meter resets on container restart, so keep a Google Cloud budget alert as the backstop.
• Keep Dockerfile, requirements.txt, and the buildspec's artifact selection (Dockerfile, backend/, requirements.txt) intact — the R2RA deploy consumes exactly that bundle shape.

Rollback path

If the co-hosted setup needs to be rolled back (for reference — not an automated process):

1. Recreate a single-instance Elastic Beanstalk environment from the retained role2-builder application versions.
2. Point the api.role2builder.org CloudFront origin back to that environment.

Learn More

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!