crystalbank

An open source project to showcase a banking system written in Crystal. The project will progress along the following domains:

1. Accounts ✅
2. Transfers ✅
3. Customers ✅
4. Users ✅
5. ApiKeys ✅
6. Authentication ✅
7. Approvals ✅
8. Roles & Permissions (Data access rights) ✅
9. Scopes (Data ownership) ⏳

Project Structure

crystalbank/
├── app/
│   ├── frontend/       # Svelte-based SPA dashboard
│   │   ├── src/        # Svelte components and application logic
│   │   ├── package.json
│   │   └── vite.config.js
│   ├── public/         # Built frontend assets (generated by build-frontend)
│   ├── src/            # Crystal backend source
│   └── spec/           # Crystal specs
├── docker-compose.yml
└── Makefile

Setup

Prerequisites

• Docker and Docker Compose

Start the environment

$ make dev

This builds the Docker image (if not already present), starts the database, API server, and API documentation services, and opens a console in the running container.

All available make targets can be listed with:

$ make help

Seed the environment

In order to access the API, the initial API credentials need to be seeded. Run this inside the console:

$ crystal src/seed.cr

This will output the initial credentials:

-----------------------------------------------------
--- Seed credentials
client_id: '0193cc51-cc9b-7955-82ca-7a6482587201'
client_secret: 'secret'
-----------------------------------------------------

Start the API server

$ crystal src/server/start.cr

The API is exposed on http://localhost:4000.

Build the Svelte frontend

The frontend is a Svelte SPA located in app/frontend/. It is built with Vite and outputs static assets into app/public/, which is served by the Crystal backend.

To build the frontend, run from the project root:

$ make build-frontend

This runs npm install && npm run build inside a node:22-alpine Docker container — no local Node.js installation required. The build produces:

• app/public/app.js — bundled JavaScript
• app/public/style.css — bundled CSS

To iterate on the frontend locally outside of Docker, use the Vite dev server directly:

$ cd app/frontend
$ npm install
$ npm run dev

Generate OpenAPI specs

To regenerate the API specification:

$ crystal src/server/start.cr -d -f openapi.json

The updated spec is automatically picked up by the running API documentation services.

View API documentation

• ReDoc: http://localhost:4002
• Swagger UI: http://localhost:4003

Access the PostgreSQL database

postgres://<user>:<password>/eventstore@localhost:4010

Contributing

1. Fork it (https://github.com/your-github-user/crystalbank/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Tristan Holl - creator and maintainer