FlowDeck

Internal operations console for triaging high-volume operational records. TypeScript + React frontend over a Python gRPC backend, with faceted filtering, optimistic action updates, and role-based access control.

Stack

• Backend: Python 3.12, grpcio + grpcio-tools + grpcio-reflection, SQLAlchemy + Postgres, Pydantic, pytest
• Frontend: React 18, TypeScript 5, Vite, TanStack Query, ConnectRPC (@bufbuild/protobuf + @connectrpc/connect-web)
• Bridge: Envoy grpc_web filter, so the browser talks gRPC-web while the backend stays pure gRPC
• Auth: JWT for the demo (see docs/rbac.md for the OIDC swap path)
• Tests: pytest + grpcio-testing + testcontainers (backend), Vitest + React Testing Library (frontend), Playwright (e2e)

Repo layout

flowdeck/
├── apps/
│ ├── web/ # Vite + React + TS + ConnectRPC client
│ └── api/ # Python gRPC server + SQLAlchemy
├── proto/ # flow.proto + buf codegen config
├── infra/envoy/ # gRPC-web bridge config
├── docker-compose.yml # api + web + postgres + envoy
└── docs/ # rbac, optimistic-updates, facets, grpc-web-bridge

Quick start

# Generate proto stubs (requires buf)
make proto
# Run the full stack
docker compose up --build
# Web: http://localhost:5173# Envoy (gRPC-web): http://localhost:8080# API (native gRPC): localhost:50051# Postgres: localhost:5432

Development

# Backendcd apps/api
python -m venv .venv &&source .venv/bin/activate
pip install -e '.[dev]'
pytest
# Frontendcd apps/web
npm install
npm run dev
npm run test

Key concepts

• Optimistic updates — how ActOnRecord mutates the cache before the server replies, and rolls back on failure
• Faceted filtering — server returns FacetCounts next to every page of records
• RBAC — viewer / operator / supervisor, enforced by a gRPC interceptor
• gRPC-web bridge — Envoy config + ConnectRPC transport choice

License

MIT