IPAI Community App Template

A lean, reusable Next.js + FastAPI monorepo template for internal IPAI apps and IPAI Community apps. One public URL per environment, staged rollout from a zero-dependency local "Hello IPAI" up to OAuth2, PostgreSQL, LiteLLM, and file storage — added later without restructuring.

Minimalinvasive by design: official generators, standard config, no monorepo build framework, platform-neutral application code.

Status

Capability	Status	Verification
Local Next.js app	Verified	make build (web) + Vitest renders "Hallo IPAI"
Local FastAPI API	Verified	pytest — apps/api/tests/test_api.py (/api/hello etc.)
Frontend-to-API request	Verified	Live /api/hello fetch through the Next rewrite (curl :3000/api/hello)
CI: lint / test / build (GitLab + Forgejo)	Implemented	CI config valid; make lint/test/build run and pass locally on the Phase 1 app code; first green remote pipeline required to upgrade to Verified
Test deployment	Not started	–
QA deployment	Not started	–
Production deployment	Not started	–
OAuth2 identity	Implemented	Header-based identity; pytest + Vitest cover header/dev-fallback/group-parsing. Verified once running behind the real oauth2-proxy.
PostgreSQL	Not started	–
LiteLLM	Not started	–
File storage	Not started	–

Status values: Not started · Implemented (code exists, unproven) · Verified (proven by a test, a green pipeline, or a reachable URL — named here) · Blocked (named blocker).

Architecture

flowchart LR
    Browser -->|/*| Proxy[OAuth2-Proxy]
    Proxy --> Web[Next.js]
    Web -->|/api/* rewrite| API[FastAPI internal]

One public URL per environment. The browser talks only to the OAuth2-Proxy, which forwards to Next.js. Next.js serves / and rewrites /api/* to an internal FastAPI address (FASTAPI_INTERNAL_URL) — the browser never learns the backend URL, and FastAPI has no public user URL. See docs/architecture.md.

Local development

Requires Node.js (for apps/web, npm) and Python with uv (for apps/api). No OAuth2-proxy, PostgreSQL, LiteLLM, or object storage is needed for local dev.

cp .env.example .env      # fill in local values (safe Phase 1 defaults)
make install              # npm ci (web) + uv sync (api)
make dev                  # web on :3000, api on :8000
make lint                 # ESLint (web) + ruff (api)
make test                 # web tests + pytest (api)
make build                # production build (web) + import check (api)

Environments

Branch	Environment	Public URL	Deployment
test	Test	<app-name>-test.apps.ip.ai	Not started
qa	QA	<app-name>-qa.apps.ip.ai	Not started
prod	Production	<app-name>.apps.ip.ai	Not started

test / qa / prod are intended as protected branches; changes via merge requests. No deployment is wired yet — CI runs lint/test/build only.

Roadmap

• Phase 0 — README, architecture, env template, Makefile, CI wrappers
• Phase 1 — Local Hello IPAI (FastAPI + Next.js; lint/test/build green in CI)
• Phase 2 — OAuth2 identity (header-based /api/me + getIdentity(); DEV_USER_* local fallback)
• Phase 3 — PostgreSQL (SQLAlchemy + Alembic; controlled migrations)
• Phase 4 — LiteLLM (managed primary/fallback keys + BYOK)
• Phase 5 — File / image storage (FastAPI upload; S3-compatible in prod)
• Deployment (STACKIT Kubernetes or Cloud Foundry — gated on real infra)

Adding another environment

1. Add the branch / environment mapping.
2. Provide the URL + DNS / platform route.
3. Add the OAuth redirect URL.
4. Provide environment-specific secrets.
5. Provide a dedicated database and storage if needed.
6. Add the deployment rule in CI.
7. Add a smoke test + the environment URL.

Review Apps (optional, later) must never touch production databases or production secrets.

Further documentation

• docs/architecture.md — architecture & routing
• Design spec
• Created when real: docs/deployment.md, docs/authentication.md, docs/database.md, docs/litellm.md, docs/storage.md