Cess Advisor

Cess Advisor 🐪🚽 is a stupid yet really useful web app that helps you find a suitable toilet when you are in a hurry.

Tech stack

TL;DR: OCaml 🐪 (Sihl) + JavaScript 🤢 (SvelteKit) + PostgreSQL 🐘

Tip

If you want to preserve your mental health, you should NOT write JavaScript code (and frontends in general). OCaml is just better.

The project started as an excuse to play around with OCaml, but I needed a frontend to make it useful. I tried to pick the simplest one and ended up with Svelte. But I absolutely fucked up and started a SvelteKit project (the docs don't mention how to setup a vanilla Svelte project). So I ended up writing SSR pages and basically two backends.

Detailed tech stack

• Backend: OCaml 🐪

  • Sihl: OCaml framework for building web apps
  • Opium: OCaml library for managing HTTP requests
  • Caqti: OCaml library for interacting with databases
  • Yojson: OCaml library for JSON serialization
  • Validate: OCaml library for validating schemas

• Frontend: JavaScript 🤢

  • Sveltekit: JavaScript framework for web development
  • Tailwind CSS: CSS framework
  • DaisyUI: Tailwind components library

• Database: 🐘

  • PostgreSQL: relational database

Deployment

TL;DR: Docker 🐳 + GitHub Actions 🤖 for backend and Cloudflare Pages ☁️ for frontend

Detailed deployment

• Backend: Docker 🐳 + GitHub Actions 🤖

  • each time a commit is pushed to the main branch, deploy-backend GitHub action is triggered
  • the action connects via ssh to the server, pulls the changes and rebuilds the Docker container
  • the backend is available at https://cessadvisorapi.favo02.dev
  • instructions:
    • add HOST, USERNAME, PORT, KEY, SCRIPT secrets to GitHub
    • add private KEY provided in secrets to allowed hosts on server
    • clone this repository on the server
    • create .env file in the root of the repository (see .env.template for reference)
    • create empty folder logs in the root of the repository
    • SCRIPT secret should cd into the repository and run git pull and docker-compose up -d --build --force-recreate

• Frontend: Cloudflare Pages ☁️

  • each time a commit is pushed to the main branch, the Cloudflare pages integration detects the change
  • the integration builds the Sveltekit app with some magic
  • the frontend is available at https://cessadvisor.pages.dev
  • instructions:
    • create a new Cloudflare Pages project
    • follow instructions to connect the project to the GitHub repository
    • set Root directory (advanced) as frontend
    • set environment variables (see frontend/.env.template)

Contributing and License

The project is licensed under the GPLv3 license.

It was licensed under CC-BY 4.0 before version 1.0 (commit a21d9f70c002aa497e5196308c6e71012211e468), so the code before that commit is licensed under CC-BY 4.0 (the license is not revokable).

Each contribution is welcome, especially building alteranive better frontends (if you are brave enough to write JavaScript code).

Please follow the conventions below.

Conventions

Commit convention

This project follows the following commit convention: <type>(<part>/<scope>): <summary>

• Type: commit type

  • feat: add new feature
  • fix: bug fix
  • refactor: code refactoring
  • build: build system (dependencies, ...)
  • test: add tests
  • docs: documentation changes
  • ci: continuous integration (github actions, ...)

• Module/Scope: commit part (mandatory) and scope (optional)

  • be/: backend
    • handlers: request handlers
    • middlewares: middleware functions
    • utils: utility module
  • fe/: frontend
    • components: components
    • pages: pages (client side)
    • ssr: server side rendered pages
    • services: interaction with backend API
    • validators: form validators
  • db/: database
    • tables: tables
  • repo: repository (omit scope)

• Summary: commit summary, present tense, start with lowercase, no period at the end

Adding new scopes is allowed if necessary, just add it to the list above.

Changelog

See CHANGELOG.md file.