Improve documentation

Makefile

@@ -16,7 +16,7 @@ lint:
 	golangci-lint run
 
 clean:
-	rm -f cacert-boardvoting
+	rm -rf cacert-boardvoting dist/ debian/README.md.gz
 
 ui/static/semantic.min.css: ${UIFILES}
 	npm install
@@ -24,4 +24,4 @@ ui/static/semantic.min.css: ${UIFILES}
 
 ui: ui/static/semantic.min.css
 
-.PHONY: clean all ui test lint
+.PHONY: clean all ui test lint

README.md

@@ -1,6 +1,6 @@
 # CAcert board voting service
 
-This project contains the source code for the CAcert board voting software.
+This project contains the source code for the CAcert board voting software running on https://motion.cacert.org/.
 
 ## Ideas
 
@@ -56,7 +56,7 @@ Local development requires
 * golang >= 1.18
 * sqlite3 and development headers
 * GNU make
-* nodejs, npm and gulp (only needed if you intend to update the [jQuery] or [Semantic UI] CSS and JavaScript)
+* nodejs, npm and gulp (only needed if you intend to update the [jQuery] or [Fomantic-UI] CSS and JavaScript)
 
 On a Debian 12 (Bookworm) system you can run the following command to get all required dependencies:
 
@@ -74,7 +74,7 @@ git clone ssh://git.cacert.org/var/cache/git/cacert-boardvoting.git
 
 To get started copy `config.yaml.example` to `config.yaml` and customize the parameters. You will also need a set of
 X.509 certificates and a private key because the application performs TLS Client certificate authentication. You might
-use `openssl` to create a self signed server certificate and retrieve the CAcert class 3 root from the CAcert website:
+use `openssl` to create a self-signed server certificate and retrieve the CAcert class 3 root from the CAcert website:
 
 ```shell script
 openssl req -new -newkey rsa:2048 -keyout server.key -x509 -out server.crt -subj '/CN=localhost'
@@ -110,7 +110,7 @@ dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64
 
 ### Debugging SMTP server
 
-You can use [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/cli.html) to setup a small testing SMTP
+You can use [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/cli.html) to set up a small testing SMTP
 server that logs to stdout:
 
 ```shell script
@@ -118,6 +118,9 @@ sudo apt install python3-aiosmtpd
 python3 -m aiosmtpd -n
 ```
 
+Another good local SMTP debugging tool is [MailHog](https://github.com/mailhog/MailHog) which provides a web based
+user interface and a REST API to inspect received mails.
+
 ### Build and run
 
 ```shell script
@@ -127,7 +130,7 @@ make
 
 ### Build UI resources
 
-[Fomantic-UI](https://fomantic-ui.com/) is used as a CSS framework. Configuration is stored in `semantic.json` in the
+[Fomantic-UI] is used as a CSS framework. Configuration is stored in `semantic.json` in the
 project root directory.
 
 Building the UI resource requires
@@ -146,26 +149,56 @@ npx gulp build
 ## Code structure
 
 ```
-.
-├── boardvoting
+├── cmd
+│   └── boardvoting
+├── config.yaml.example
+├── debian
+├── go.mod
+├── go.sum
+├── internal
+│   ├── app
+│   ├── forms
+│   ├── handlers
+│   ├── jobs
+│   ├── mailtemplates
+│   ├── mailtemplates.go
+│   ├── middleware
 │   ├── migrations
-│   ├── static
-│   └── templates
-├── db
-└── semantic
+│   ├── migrations.go
+│   ├── models
+│   ├── notifications
+│   └── validator
+├── Jenkinsfile
+├── LICENSE
+├── Makefile
+├── package.json
+├── package-lock.json
+├── README.md
+├── semantic.json
+└── ui
+    ├── efs.go
+    ├── html
+    ├── semantic
+    └── static
 ```
 
-The `boardvoting` directory contains the application code, database migrations, static assets and [Go templates] for
-HTML pages and mail content.
+The `cmd/boardvoting` directory contains the application code.
 
-The `db` directory contains the initializer for database migrations.
+The `internal/migrations` directory contains database migration scripts.
 
-The `semantic` directory contains a download of [Semantic UI]
+Static assets and [Go templates] for HTML pages are stored in `ui/static` and `ui/html`.
 
-The entry point into the application is `boardvoting.go` in the top level directory. `Makefile` controls the build
-`Jenkinsfile` contains the pipeline definition for the [Continuous Integration Job]. `package-lock.json` contains the
-pinned versions of external JavaScript and CSS assets (use `npm install` to download them into a local `node_modules`
-directory). `semantic.json` is the configuration file for the [Semantic UI] CSS framework.
+Email templates are stored in `internal/mailtemplates`.
+
+All Go code besides the main application is stored in subdirectories of `internal`.
+
+The `ui/semantic` directory contains a download of [Fomantic-UI].
+
+The entry point into the application is `cmd/boardvoting/main.go`. `Makefile` controls the build
+`Jenkinsfile` contains the pipeline definition for the [Continuous Integration Job].
+`package-lock.json` contains the pinned versions of external JavaScript and CSS assets (use
+`npm install` to download them into a local `node_modules` directory). `semantic.json` is the
+configuration file for the [Fomantic-UI] CSS framework.
 
 [Continuous Integration Job]: https://jenkins.cacert.org/job/cacert-boardvoting/
 
@@ -175,4 +208,4 @@ directory). `semantic.json` is the configuration file for the [Semantic UI] CSS
 
 [jQuery]: https://jquery.com/
 
-[Semantic UI]: https://semantic-ui.com/
+[Fomantic-UI]: https://fomantic-ui.com/

debian/copyright

@@ -1,7 +1,7 @@
 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: CAcert board voting software
 Upstream-Contact: Jan Dittberner <jandd@cacert.org>
-Source: https://git.cacert.org/gitweb/?p=cacert-boardvoting.git
+Source: https://code.cacert.org/cacert/cacert-boardvoting.git
 
 Files: *
 Copyright: 2017-2022 Jan Dittberner