Faststamps is a responsive web-application for managing a stamp collection. This is a sandbox project for trying out FastAPI & HTMX in a tiny micro-service based system, and also for trying out some new technology and ideas. If you happen to stumble over this repo, please note it is far from a "1.0 release" and I only work on it sporadically.
Since it is a responsive web-application, you can use it in your mobile phone to keep track of your stamp collection.
It consists of three components:
- A web application stamp-app written in HTMX and Bulma served by FastAPI packaged as a Docker images.
- A backend consisting of two micro-services packaged as Docker images:
- A read-only HTTP/JSON API stamp-catalog-api implemented with FastAPI and containing a stamp catalog, using a CSV file as a database read into a Pandas dataFrame at startup.
- A HTTP/JSON API stamp-collection-api implemented with FastAPI and containing my collection of stamps, using TinyDB or unQLite as a database.
The first iteration has a simple authentication mechanism in place in the form of a configuration file containing the single user and that user's salted password hash. Also the first iteration does not make use of FastAPI async support and does not use a multithread-safe database solution.
The entire app is intended to be run as three Docker containers with Docker compose. It can run on your laptop or be deployed on a home server, or on a virtual server with a VPS provider with Docker and Docker compose. Of course, if you want to access it on your phone from anywhere, you need to deploy it on a server you can access from anywhere.
The total requirements are as follows, but note that the Faststamps app, Catalog API and Collection API are separate applications and have slightly different dependencies. These are the total dependencies:
- Python 3.10 but should probably work with Python 3.8+.
- FastAPI.
- uvicorn.
- HTMX.
- Bulma.
- Jinja2.
- httpx.
- Pandas.
- Some embeddded database like TinyDB, unQLite or SQLite. I haven't decided yet.
- Docker and Docker compose.
- Pytest.
Clone the repo:
git clone git@github.com:pacoispaco/faststamps.gitTo start up a local running instance:
docker-compose up --build -dThe above will build all Docker images and start them up as containers, and will make the web app available at http://127.0.0.1:8080
Each separate component has its own directory and also its own development and test setup. Read the README.md file for each component:
Bare in mind this a personal sand-box project for trying out new technology and ideas.
Here is a simple visualization of the runtime setup (architecture) with three Docker containers:
graph TD;
id1(stamp-app: Uvicorn)-->id2(Catalog API: Uvicorn);
id1(stamp-app: Uvicorn)-->id3(Collections API: Uvicorn);
Arrows denote dependencies and request/response initiators.
The core idea is to separate the catalog of stamps from a personal collection of stamps. We implement these two concepts as two different information domains, each with their own bounded context and internal data model. The shared information between the two information domains is constrained to the basic concept of a "stamp" that has a unique "id". By sharing this information the both information domains can together, provide a basis for an app where a user can keep track of his/her stamp collection as related to a stamp catalog.
Note that the two information domains, the catalog of stamps and the personal collection of stamps, have different internal models of what a stamp is, yet they have a shared general understanding of what a stamp is and how to identify it.
By separating the system into two different information domains, and thus two separate API:s, we gain a cleaner separation of concerns, we facilitate working on separate parts of the system and make it easier to fix, adapt and upgrade these parts independently of each other. Hopefully we also provide a structure to the system that makes it easier to understand. However, this also comes at a cost. We need to maintain two separate API:s with their associated unit tests and documentation, and we also get a more complicated run time setup.
By using HTMX we can write a web app behaving like a SPA while at the same time avoiding to have to use a large Javascript framwork.
This project is released under GNU GPLv3.