Infiapp

Infiapp is a minimal, opinionated framework for building web applications. It abstracts infrastructure deployment and management into maintainable, secure repo conventions so builders can vibe code applications with a practical level of production readiness.

The framework keeps four concepts small and explicit:

• Agents are AWS Lambda functions. Each agent owns its runtime code, tests, and spec.json.
• DynamoDB tables are declared in repo specs. Tables are owned by agents and generated into helper APIs for agent reads and writes.
• WebUI is one Next.js application. External agents are exposed to it through generated API clients and mocks.
• Repo Tools validate specs, generate code, run tests and manage infrastructure.

Repository Layout

agents/
  README.md                  Agent folder contract and spec reference
  shared_utils/              Shared Python utilities copied onto every Lambda path
  sample_agent/
    code/                    Lambda handler and implementation
    test/                    Agent unit tests
    spec.json                Agent definition
dynamodb/
  README.md                  DynamoDB table spec
  sample_agent/
    sample_messages.json     Demo message table owned by sample_agent
pyproject.toml               Repo-wide pinned Python dependency manifest
repo_tools/
  python_dependencies.py     Resolves pinned Python dependencies from pyproject.toml
  codegen.py                 Generates DynamoDB helpers and WebUI agent clients
  validate_agents.py         Validates Lambda agent specs
  validate_dynamodb.py       Validates table specs and key compatibility
  check_deployed_state.py    Compares deployed infra with repo definitions
  deploy.py                  Deploys DynamoDB, Lambda agents, and Vercel WebUI
webUI/
  app/                       Next.js App Router application
  src/lib/generated/         Generated external agent clients and mocks
.github/workflows/
  test-agents.yml            Agent spec validation, agent tests, Python compile checks
  test-db.yml                DynamoDB spec validation and generated-code checks
  test-webUI.yml             WebUI build, Playwright E2E and screenshot checks
  deploy.yml                 Main-only deploy workflow
  verify-deployed-state.yml  Main-only deployed-state verification

Agents

Agents are Python Lambda functions defined by folder-level specs. Each agent owns its code, tests, and any DynamoDB tables declared for it. Agents can be internal or external; external agents get generated WebUI clients.

See agents/README.md for the required folder structure, spec.json fields, framework defaults, shared utilities, and test expectations.

DynamoDB

DynamoDB tables are declared as JSON specs under dynamodb/<agent_name>/. Each table belongs to the agent named by its parent folder, and repo tools generate shared Python helpers from these specs, including typed item objects, single-item reads, sort-key range queries, and item puts.

See dynamodb/README.md for the table spec format, supported attribute types, defaults, and key compatibility rules.

WebUI

webUI/ is a single Next.js App Router application. It can call external Lambda agents through generated helpers, uses generated agent mocks for local development, and should be tested with build checks and Playwright E2E screenshots.

See webUI/README.md for WebUI conventions, generated helper usage, local mock behavior, and test expectations.

Repo Tools

repo_tools/ contains the Python command runner, validators, code generators, deploy tooling, and deployed-state verification. Run it from an activated Python virtual environment.

See repo_tools/README.md for the command reference and generated file list.

Getting Started

Fork this repo into your own GitHub account or organization, then clone your fork.

Required local tools:

• Python 3.11 is needed. On macOS:

  brew install python@3.11

• Node.js 22 is needed. On macOS:

  brew install node@22

Create a Python virtual environment:

python3.11 -m venv .venv
source .venv/bin/activate

Rename the starter app before building on it:

python -m repo_tools rename-app my-app-name --title "My App Name"

Install Python dependencies:

python -m pip install ".[dev]"

Install Node dependencies:

npm --prefix webUI install

Install the Playwright Chromium browser for local WebUI E2E and screenshot tests:

npm --prefix webUI exec playwright install chromium

Run the WebUI against generated agent mocks:

INFIAPP_AGENT_BACKEND_MODE=mock npm --prefix webUI run dev

Open http://localhost:3000 in a browser.

Deployment

Create the AWS secrets:

1. Use a dedicated AWS account for this app if possible.
2. In the AWS Console, go to IAM > Users > Create user.
3. Name the user infiapp-control-plane.
4. Choose Attach policies directly and attach the AWS managed policy AdministratorAccess.
5. Open the new user, go to Security credentials > Create access key.
6. Choose Third-party service as the use case.
7. Copy the Access key ID into GitHub as AWS_ACCESS_KEY_ID.
8. Copy the Secret access key into GitHub as AWS_SECRET_ACCESS_KEY.
9. Set AWS_REGION to the AWS region you want to deploy into, for example us-east-1.

Create the Vercel secrets:

1. Create or choose the Vercel team that should own the WebUI project.
2. In Vercel, open Personal Settings > Tokens.
3. Create a token and choose the team that owns the app as the scope. Set Expiration to never. Copy the token and add it to GitHub as VERCEL_TOKEN.
4. In Vercel, open the owning team's Settings > General page.
5. Copy the Team ID, which starts with team_, and add it to GitHub as VERCEL_TEAM_ID.

No need to install the Vercel GitHub app for this repo. Infiapp deploys the WebUI from the GitHub Actions deploy workflow.

Add all secrets in GitHub under Repository > Settings > Secrets and variables > Actions > Repository secrets.

After setup, deploy from GitHub Actions:

1. Open Actions > deploy in GitHub.
2. Select Run workflow on the main branch.
3. Wait for the workflow to finish.

Deployed State Verification

Verify deployed infrastructure from GitHub Actions:

1. Open Actions > verify-deployed-state in GitHub.
2. Select Run workflow on the main branch.
3. Wait for the workflow to finish.