Protoapp - Batteries Included

This repository is an opinionated fork of adl-lang/protoapp that is suitable for building modern full-stack web applications. It uses ADL as the "typing glue", enabling strong cross-language type-safety from the database to the user interface.

The technology stack consists of:

• postgresql for the relational store
• rust + poem + sqlx for the application server
• typescript + react for the web user interface

More information on ADL, the API Workbench and the underlying tech stack can be found in the upstream README.

ADL

ADL is a framework for building cross language data models. In this repo we use ADL to define

• the relational database schema
• the client/server http based API
• the server config file format

From these, we generate:

• the postgres SQL for the db schema
• the rust db schema binding
• the rust api binding (used here)
• the typescript api binding (used here)

Opinionated defaults

After forking or cloning this template, you are free to change any part of the tooling and software architecture as you see fit.

The most opinionated part of the codebase is the ts/ui frontend project, which implements a simple messaging app. Adding a new frontend of any project is as easy as adding a new pnpm package and including @protoapp/adl as a workspace dependency.

The current UI was generated with Vite and uses the react-ts template. Additional patterns for testing, routing and components are established for reference.

For example, the template uses:

• shadcn/ui for visual components
• tailwindcss for styling
• storybook for testing and iterating on the interface

Local setup

Currently Linux and macOS are supported.

Install docker and rust/cargo for your platform. Then install deno, node, pnpm, and adl into a repo local directory by sourcing the local setup script:

. deno/local-setup.sh

Check installed tool versions with:

deno --version
node --version
adlc show --version

Development loop

When you've changed any ADL, regenerate rust/typescript/sql code with

deno task genadl

Starting postgres

(cd platform/dev; docker compose up -d db)

Running server tests

(
cd rust/server
export DB_CONNECTION_URL=postgresql://postgres:xyzzy@localhost:5432/appdb
cargo test -- --test-threads=1
)

Starting the server

(
cd rust/server
export PROTOAPP_SERVER_CONFIG='{
  "http_bind_addr": "0.0.0.0:8081",
  "db": {
    "host": "localhost",
    "port": 5432,
    "dbname": "appdb",
    "user": "postgres",
    "password": "xyzzy"
  },
  "jwt_access_secret": "shouldbetrulysecretbutnotrightnow",
  "jwt_refresh_secret": "nottomentionthisone"
 }'
export RUST_LOG=info
cargo run --bin protoapp-server
)

This will create the db schema and/or apply any necessary migrations

Creating test users

(
cd rust/server
export DB_CONNECTION_URL=postgresql://postgres:xyzzy@localhost:5432/appdb
cargo run --bin protoapp-tools -- create-user [email protected] Joe xyzzy1
cargo run --bin protoapp-tools -- create-user --is-admin [email protected] Sarah abcdef
)

Starting the UI in dev mode

(
cd ts/ui
# note pnpm is installed by local-setup.sh
pnpm install
pnpm run dev
)

Starting the API Workbench in dev mode

(
cd ts/api-workbench
# note pnpm is installed by local-setup.sh
pnpm install
pnpm run dev
)

The web application will be accessible at: http://localhost:5173 The api workbench will be accessible at: http://localhost:5174

Forking

The following linux commands can be used to rename "protoapp" to "myproject" in a fork of this repo:

git mv adl/{protoapp,myproject}
git mv rust/adl/src/gen/{protoapp,myproject}
git mv rust/server/src/bin/{protoapp,myproject}-server.rs
git mv rust/server/src/bin/{protoapp,myproject}-tools.rs
git mv ts/adl/src/{protoapp,myproject}
sed -i -e 's|protoapp|myproject|g'  $(git ls-files)
sed -i -e 's|Protoapp|MyProject|g'  $(git ls-files)
sed -i -e 's|PROTOAPP|MYPROJECT|g'  $(git ls-files)
deno task genadl

macos sed doesn't support multi file in place updates, so an alternative tool will be required.