This repository contains the code for an internal operations web app, designed by members of Moneyless Society for the public to consume. Some pages may be particular to our own NPO's operations, but ultimately this serves as a test-bed for a blank-label, open-source solution to organizing a rhizomatically structured organization according to sociocratic and/or holarchic principles.
This web app is coded in TypeScript, HTML, and CSS using the performant and intuitive SvelteKit framework. It structures its data with Prisma ORM with some optimization for a PostgreSQL database.
SvelteKit is a fullstack framework written to mimic vanilla JavaScript/TypeScript and HTML, but greatly extend the functionality of some basic conventions in a way that works in a fullstack context.
PostgreSQL (AKA Postgres) is compatible with Prisma, which is our first choice of database development tool, and it's easy to host on Railway, which is a hosting service we're familiar with. Postgres is well-suited for scalable and fast database operations with various data integrity features built in.
Prisma ORM provides a simple way to work with an existing database: define the shape of data in a schema.prisma file (or, if so configured, a folder of schema files), plug in connection info, and presto: Prisma has CLI commands to generate and apply changes to the database and files for your source code. Thanks to this ORM and some community plugins, this app configures Prisma to generate many things:
- TypeScript ORM client for interacting with our chosen database
- Zod types for runtime type validation
- ERD (Entity Relationship Diagram)
- DBML (DataBase Markup Language)
- Database migrations
The API will be scaffolded with tRPC, much of that code being generated by Prisma.
Prisma also generates for us Zod types to use for parsing and validating data on the client or server side.
To get working on this repo, first fork the repository to your personal GitHub account. Clone that repository in your local development environment.
Open a terminal to initialize and run the project:
# install the project dependencies
`npm install`
# Generate a Prisma client to
# start a local development server
npm run dev
# or, when starting the server, you can optionally open the app in a new browser tab
npm run dev -- --openThis project is set up for PostgreSQL, which you can install and run on your computer. To create a test database, you can use pgAdmin, which should be bundled in the PG installer. To connect to that database, create/update your .env file in the TLD (top level directory) to define PG_URL as your new database's connection string.
The abstraction that Prisma provides makes it easy to switch to a different database if we decide to at any point. There are just some features in the schema file that are specifically for PostgreSQL, which would need to be changed to suit the desired DB. PG is a good database though.
Some changes to existing data can be made non-destructively, but others require manual SQL migrations.
When you want to change the shape of data in our code and our database simultaneously, you change the Prisma file, and then do some Prisma things to apply the changes.
npx prisma generate # Generates client, ERD, DBML, TS types, and Zod types
npx prisma migrate dev # Creates and applies SQL migration to development databaseLinting and auto-formatting settings are defined in the .vscode folder. Add new preferences there, or tell us why we should change existing settings.
To create a production version of this app:
npm run buildYou can preview the production build with npm run preview.
To deploy your app, you may need to install an adapter for your target environment.