No description
  • C# 85.8%
  • HTML 6.6%
  • CSS 4.5%
  • JavaScript 2.8%
  • Shell 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Lars Richter 7b811aa23d
All checks were successful
Build and test / test (push) Successful in 1m30s
Merge branch 'feature/code-checks'
2026-11-13 22:57:16 +01:00
.forgejo/workflows Build and test every push and show the result on Forgejo 2026-11-01 09:14:30 +01:00
.githooks Run the unit tests before each push 2026-11-13 22:49:54 +01:00
.vscode Add functionality to export contacts to a CardDav server 2026-05-05 11:10:52 +02:00
docs/superpowers Keep building when a NuGet package gets a security advisory 2026-11-13 22:56:22 +01:00
images Describe the new look, setup and deployment in the README with fresh screenshots 2026-10-25 21:16:04 +01:00
keycloak-theme/peopleiknow/login Give the Keycloak login page the app's look 2026-11-06 21:47:07 +01:00
PeopleIKnow Format the C# code consistently 2026-11-13 22:45:54 +01:00
PeopleIKnow.UITests Format the C# code consistently 2026-11-13 22:45:54 +01:00
PeopleIKnow.UnitTests Format the C# code consistently 2026-11-13 22:45:54 +01:00
.editorconfig Refuse to build badly formatted code or code with warnings 2026-11-13 22:47:38 +01:00
.gitignore Serve contact photos through an authorized action instead of static files 2026-10-26 00:35:52 +01:00
AGENTS.md Give an example of a stub warning that actually fails the build 2026-11-13 22:56:22 +01:00
CLAUDE.md Add guidance for coding agents 2026-10-29 16:17:01 +01:00
Directory.Build.props Keep building when a NuGet package gets a security advisory 2026-11-13 22:56:22 +01:00
global.json Migrate to .NET 10 2026-10-24 00:09:30 +02:00
LICENSE Create LICENSE 2021-10-14 23:04:45 +02:00
PeopleIKnow.sln Remove the CSV import and CardDAV export tools 2026-10-24 16:39:59 +02:00
README.md Describe the formatting checks and the pre-push tests 2026-11-13 22:51:10 +01:00

People I Know

Build and test

"People I Know" is a PRM. Screenshot

What is a PRM?

A PRM is a "Personal Relationship Management". On the web, you will also find the name "Personal CRM". So you can use "People I Know" to store information about the people you know. ;-)

Is it like my "Contacts" app on my phone?

Yes, somehow it is.

So, why would I use it?

There were a few reasons for me to build this application. For "normal" contact management, the standard Android or iOS app would be fine. But there was something missing for me.

  1. If you use the before mentioned services, you don't own your data. It is stored somewhere in Apple's or Google's cloud services.
  2. The standard apps / services do not provide good possibilities to store some kind of timeline / updates for the contacts. You still have the "Notes" field, but it is limited to a multi-line text.
  3. At least in Google Contacts you can store "Relationships" of a contact to other people. But that feature is also limited to a key-value-pair. No real links to other contacts etc.

So the main goal of this application is to do standard contact management plus

  1. You own your data. It is stored in your database.
  2. You can keep a timeline for each contact: status updates and the things you did together, sorted by date.
  3. You can store relationships to other people and link them to their contacts.

Features

  • A profile for every contact. Photo, name, job, phone numbers, email addresses, address and tags at a glance. Phone numbers and email addresses are links, so one tap calls or writes.
  • Jot down what's new in one step. The "What's new with Max?" box at the top of the timeline saves a status update dated now. Multi-line notes keep their line breaks.
  • One timeline. Status updates and common activities are shown together, newest first, with year dividers. Notes and activities can carry photos and PDFs (tickets, a menu, a picture from the day): photos show as thumbnails, PDFs as a link.
  • Shared activities. An activity (a call, a dinner, a trip) can have several participants and shows up in each participant's timeline.
  • Linked relationships. "Sister: Anna Becker" links to Anna's contact. If someone lists a contact as their friend, the contact shows that too and offers to add the reverse relationship.
  • Gifts. Keep track of gifts you received, gifts you gave and ideas for gifts.
  • Reminders. One-off or yearly, optionally sent to you via ntfy or Telegram (see below).
  • Coming up. The start page shows birthdays and reminders in the next 30 days (on larger screens).
  • Birthdays. All birthdays grouped by month, next one first, with the age people turn when the year is known.
  • Tags. Label people ("work", "football") and pick from the tags you already use when editing a contact. A tag page lists everyone with that tag, reached from the profile, from search results or from the "Tags" overview in the top bar, which shows how many people have each tag. There you can rename a tag for everyone at once (renaming onto an existing tag merges the two) or delete it; the people stay. Tags ignore case, and a tag disappears when nobody has it anymore.
  • Favorites and search. Favorites are pinned on top of the list; search filters by name or the beginning of a tag while you type.
  • Made for phone and computer. The layout works from 360px phones to desktops, can be installed as an app (PWA), follows the system's light or dark mode and is available in English and German.

Coming up on the start page, dark mode

On the phone: the contact list, a contact and the timeline in dark mode

Relationships

In the past, one of my main problems always was remembering the relationships between various people. "What was the name of John's son again?", "Is Mark a cousin of Lisa or a cousin of Noah?".

Today, I just check the respective contact and see the relationships to other people in seconds. Each relationship is a "Relationship - Name" pair, like "Wife - Jane Smith". If Jane is in "People I Know" too, the name links to her contact.

Status Updates / Timeline

"People I Know" makes it easy for you to keep track of recent things in the life of your friends/contacts. Just add updates to the timeline of your contacts. Before you meet your friends again, just check their contact in "People I Know" and you can ask about the exam they had a week ago or about the broken leg of their brother.

Common activities

Store information about common activities with your contacts. No more "When was the last time we met Carl?". Just check "People I Know" and you will instantly know it. The profile even shows "Last seen 9 days ago".

Gifts

Sometimes it is hard to remember what you got someone as a birthday present last year. Or you are looking for a gift for Michael and this one book would be perfect for him. But you are not sure if it was Anne or Michael who gave it to you for your birthday.

That's why you can keep track of gifts in "People I Know". Keep track of presents anyone gave you, presents you gave to your contacts, or even ideas for presents.

Getting started

What you need

  • The .NET 10 SDK.
  • An OpenID Connect provider for the login. "People I Know" is used with Keycloak; other providers should work as long as they deliver the role claim described below.

There is no database to install: the app creates its SQLite database people.db on the first start and applies schema updates automatically on every start. An empty database is filled with a few demo contacts.

Set up the login (Keycloak)

  1. Create a realm (or use an existing one) and a client, e.g. peopleiknow-web, with client authentication turned on and the standard (authorization code) flow enabled.
  2. Add your app's URL to the client's valid redirect URIs, e.g. https://pik.example.com/* (and https://localhost:5001/* for local development).
  3. Create a realm role user and assign it to everyone who may use the app. All pages require this role.
  4. Make the roles reach the app as a role claim: add a "User Realm Role" mapper to the client (or its dedicated scope) with token claim name role, multivalued, and "Add to ID token" and "Add to userinfo" turned on.

Give the login page the app's look (optional)

keycloak-theme/peopleiknow is a login theme for Keycloak 26 with the app's colours, fonts and name, in light and dark mode. It builds on Keycloak's own keycloak.v2 theme and only adds a stylesheet, so Keycloak upgrades don't need theme changes.

  1. Copy the folder keycloak-theme/peopleiknow into Keycloak's themes directory, e.g. /opt/keycloak/themes/peopleiknow (with Docker, mount it there), and restart Keycloak.
  2. Select it for the app's client only: Clients → peopleiknow-web → Login settings → Login theme peopleiknow. Other applications in the realm keep their look.
  3. For German: Realm settings → Localization → turn on internationalization with English and German. The app then shows the login page in the language it was showing itself (it sends ui_locales).

While changing the theme, run Keycloak with start-dev, which doesn't cache themes, so a reload shows your changes. The theme carries copies of the app's design tokens, fonts and images; KeycloakThemeTests fails when they differ from the app's, so change both together.

Configure the app

Settings live in PeopleIKnow/appsettings.json. Override them per environment in appsettings.Production.json (or appsettings.Development.json), or with environment variables like Keycloak__ClientSecret.

Setting What it is
ConnectionStrings:Contacts SQLite connection string, default Data Source=people.db
ContactImages:Directory Where uploaded photos are stored. Empty keeps them in App_Data/contact-images under the app folder; set a path outside the app (relative to the app folder or absolute) so deployments don't touch them. Photos are never served as static files, only to signed-in users. Accepted: JPEG, PNG, WebP and GIF up to 10 MB (and 40 megapixels); they are re-encoded to JPEG and scaled down to 1024 px
Attachments:Directory Where photos and PDFs attached to notes and activities are stored. Empty keeps them in App_Data/attachments under the app folder; set a path outside the app (relative to the app folder or absolute) so deployments don't touch them. Required as soon as ContactImages:Directory is set, so attachments don't end up in the app folder by accident. Never served as static files, only to signed-in users. Photos are re-encoded to JPEG and scaled down to 2048 px (with a 480 px thumbnail), PDFs are kept as uploaded
Keycloak:Authority Your realm's URL, e.g. https://keycloak.example.com/realms/peopleiknow
Keycloak:ClientId / Keycloak:ClientSecret The client from the login setup
Keycloak:ApiAudience The audience API tokens must be issued for, default peopleiknow-api (see Use the API). Must not be empty
Keycloak:ApiRole The role API tokens must carry, default api-notes
Notifications:Enabled true to send reminders
Notifications:Provider Where reminders go: Ntfy or Telegram
Notifications:Ntfy:Url / Topic Your ntfy server (default https://ntfy.sh) and the topic to publish to
Notifications:Ntfy:AccessToken Optional access token, for servers that restrict the topic
Notifications:Ntfy:AppUrl Optional public address of this app; tapping a notification and its "View contact" button open the contact
Notifications:Ntfy:IncludePhoto true (default) attaches the contact's photo; needs attachments enabled on the ntfy server
Notifications:Ntfy:DefaultCountryCode Country code for numbers stored without one, e.g. +49, so they work with the Signal, WhatsApp and Call buttons
Notifications:Ntfy:Actions Up to three buttons on notifications about a contact, in this order: ViewContact, Signal, WhatsApp, Call, Email. Default ["ViewContact", "Signal", "Email"]; [] shows none
Notifications:Telegram:Token / ChatId Your Telegram bot's token and the chat it writes to
Notifications:Time:Hour / Minute When the daily reminders are sent (server time)
Serilog Logging; by default to the console and to logs/log.txt, one file per day

Run it locally

dotnet run --project PeopleIKnow

Then open https://localhost:5001. The CSS and JS bundles (site.min.css, site.min.js) are generated on every build from bundleconfig.json.

Use the API (e.g. from a bot)

Other programs, like a Signal bot, can find contacts by name and add notes. They sign in with their own Keycloak client (a service account), not with your login, and can do nothing else: no other contact data, no changes besides adding notes, no web pages.

Set up a client for the bot (Keycloak)

  1. Create a client, e.g. peopleiknow-bot, with client authentication and "Service accounts roles" turned on and the standard flow and direct access grants turned off. Its credentials tab has the secret the bot uses.
  2. Create a realm role api-notes and assign it to the client's service account (tab "Service accounts roles"). Don't give the bot the user role.
  3. Add two mappers to the client (or its dedicated scope), both with "Add to access token" turned on:
    • "User Realm Role" with token claim name role, multivalued,
    • "Audience" with included custom audience peopleiknow-api (the value of Keycloak:ApiAudience).

The bot fetches a short-lived access token and sends it along; when it expires (after 5 minutes by default), it fetches a new one:

TOKEN=$(curl -s https://keycloak.example.com/realms/peopleiknow/protocol/openid-connect/token \
  -d grant_type=client_credentials -d client_id=peopleiknow-bot -d client_secret=... | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" "https://pik.example.com/api/contacts?name=Anna%20Schmidt"
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Met for coffee"}' https://pik.example.com/api/contacts/7/notes

Endpoints

Request What it does
GET /api/contacts?name=Anna Schmidt Contacts whose name contains every word of the text, ignoring case, so "Anna Schmidt" also finds "Anna Maria Schmidt" (tags aren't searched). Returns [{ "id": 7, "fullName": "Anna Maria Schmidt", "employer": "ACME", "tags": ["work"] }], an empty list if nobody matches, 400 without name
POST /api/contacts/{id}/notes Adds a note. Body { "text": "...", "created": "2026-10-27T18:30:00" }; created is optional (default: now), a value without time zone is taken as server time. Returns 201 with { "id", "contactId", "text", "created" }, 404 for an unknown contact, 400 without text

Without a valid token the API answers 401, with a token lacking the role 403.

Reminders

"People I Know" can send you your reminders as push notifications, through ntfy or a Telegram bot. Set Notifications:Provider, fill in the settings for that provider and set Enabled to true:

  • ntfy: set Ntfy:Url to your server (or leave the public https://ntfy.sh) and Ntfy:Topic to the topic you subscribe to in the ntfy app. If your server restricts the topic, create an access token (ntfy token add <user>) with write access to it and put it into Ntfy:AccessToken. On the public server, anyone who knows the topic name can read it, so pick one that is hard to guess. Notifications about a contact come with the contact's photo and up to three buttons, by default "View contact" (needs Ntfy:AppUrl), "Message on Signal" and "Send email". Pick others with Ntfy:Actions, e.g. ["ViewContact", "WhatsApp", "Call"]. The Signal, WhatsApp and Call buttons use a number typed "Mobile" or "Handy", otherwise the first one. A button is left out when the contact has no number or email for it. The photo is uploaded as an attachment, so your server needs attachment-cache-dir and base-url set; if the upload is refused, the notification goes out without the photo. Turn photos off with Ntfy:IncludePhoto: false, especially on the public server, where anyone who knows the topic sees them.
  • Telegram: create a bot with @BotFather and put its token and your chat id into Telegram:Token and Telegram:ChatId.

The app checks these settings on startup and refuses to start if notifications are enabled but incomplete. Once a day, at the configured time, it sends you:

  • the birthdays of the day, for contacts with "Send birthday notification" turned on (in the contact's Edit page),
  • the reminders due that day, including yearly ones like anniversaries.

Deployment

The app is a regular ASP.NET Core app. A deployment that keeps your data safe looks like this:

  1. dotnet publish PeopleIKnow -c Release --self-contained=false and copy the publish folder to the server.
  2. Keep the data outside the app folder, so a new version never overwrites it: point ConnectionStrings:Contacts to the database, ContactImages:Directory to the photo folder and Attachments:Directory to the attachment folder there, and keep appsettings.Production.json next to them.
  3. Run it as a service (e.g. systemd) with ASPNETCORE_ENVIRONMENT=Production behind a reverse proxy that terminates HTTPS. Set ASPNETCORE_FORWARDEDHEADERS_ENABLED=true so the login redirects use https. If your reverse proxy limits request bodies (nginx: client_max_body_size), allow at least 100 MB: one save can carry up to 10 photos and PDFs.
  4. Database schema updates are applied automatically when the new version starts. Back up first (see below).

Upgrading

The login now asks Keycloak for the app's language (ui_locales). Nothing needs to change; to get the German login page and the app's look on it, see Give the login page the app's look.

Tags are now their own records. Existing comma-separated tags are converted automatically on the first start: only commas separate tags, so an old tag like "football family" or "football; family" stays one tag, and variants that differ only in case become one tag. Non-ASCII letters are the exception ("Ärger" and "ärger" stay two tags until you merge them by renaming one). Searching now matches the beginning of a tag: "foot" finds "football", "ball" no longer does.

  • The previous release can't read the database after this migration, so rolling back past this release needs either the pre-deploy database backup (tag edits made since are lost) or running the migration's Down SQL by hand. Stop the service first, run the SQL, then switch to the old release. Tags created, renamed or merged since are flattened back to comma-separated text:

    sqlite3 ~/pik/shared/people.db "ALTER TABLE Contacts ADD COLUMN Tags TEXT; UPDATE Contacts SET Tags = (SELECT group_concat(Name, ', ') FROM (SELECT t.Name FROM ContactTag ct JOIN Tags t ON t.Id = ct.TagsId WHERE ct.ContactsId = Contacts.Id ORDER BY t.Name)); DROP TABLE ContactTag; DROP TABLE Tags; DELETE FROM __EFMigrationsHistory WHERE MigrationId = '20261101232104_StoreTagsSeparately';"
    

Birthdays are now stored as day and month with an optional year. Birthdays with the year 1900 or earlier (such as

  1. become "year unknown" when the migration runs on startup.
  • Rolling back past this release needs either the pre-deploy database backup (birthday edits made since are lost) or running the migration's Down SQL by hand (this needs SQLite 3.35 or newer for DROP COLUMN). Stop the service first, run the SQL, then switch to the old release. A birthday without a year comes back as 1900, or 1904 for 29 February:

    sqlite3 ~/pik/shared/people.db "ALTER TABLE Contacts ADD COLUMN Birthday TEXT NOT NULL DEFAULT '0001-01-01 00:00:00'; UPDATE Contacts SET Birthday = printf('%04d-%02d-%02d 00:00:00', COALESCE(BirthYear, CASE WHEN BirthdayMonth = 2 AND BirthdayDay = 29 THEN 1904 ELSE 1900 END), BirthdayMonth, BirthdayDay) WHERE BirthdayMonth IS NOT NULL; ALTER TABLE Contacts DROP COLUMN BirthdayDay; ALTER TABLE Contacts DROP COLUMN BirthdayMonth; ALTER TABLE Contacts DROP COLUMN BirthYear; DELETE FROM __EFMigrationsHistory WHERE MigrationId = '20261030203319_StoreBirthdaysWithOptionalYear';"
    

The API brings the settings Keycloak:ApiAudience (default peopleiknow-api) and Keycloak:ApiRole (default api-notes). Upgrading works without changes; set them in appsettings.Production.json only if your Keycloak mappers use other values. If ApiAudience is set to an empty value, the app does not start and says so in the log.

Notification settings are now grouped by provider. If you use Telegram reminders, move Notifications:Token and Notifications:ChatId to Notifications:Telegram:Token and Notifications:Telegram:ChatId and add "Provider": "Telegram". With notifications enabled and no provider set, the app does not start and says so in the log.

Photos are now stored under generated names, served only to signed-in users and no longer as static files. Old ImagePath values are migrated automatically on startup.

  • After deploying, files in ~/pik/shared/images named {id}.{ext} that no contact references can be removed by hand. They are no longer served, so this is housekeeping only. To compare, list what the database references and what is on disk:

    sqlite3 ~/pik/shared/people.db "SELECT ImagePath FROM Contacts WHERE ImagePath IS NOT NULL"
    ls ~/pik/shared/images
    
  • Rolling back past this release (the deploy script's --rollback) needs either the pre-deploy database backup or running the migration's Down SQL by hand, because the old release expects images/contacts/ in front of the file names:

    sqlite3 ~/pik/shared/people.db "UPDATE Contacts SET ImagePath = 'images/contacts/' || ImagePath WHERE ImagePath IS NOT NULL"
    

    Photos uploaded while rolled back keep working after upgrading again.

  • If you never configured ContactImages:Directory, earlier uploads sit in wwwroot/images/contacts. Files there are no longer served at all (the app answers 404 for /images/contacts). Moving them into the new photo directory (App_Data/contact-images) keeps the photos; otherwise delete them when upgrading.

  • If ContactImages:Directory is set, set Attachments:Directory too (a folder next to the photo folder). The app refuses to start without it, so attachments don't end up in the app folder, where the next release would take them along. Include the folder in your backups. Attachments:Directory must be its own folder: the app also refuses to start if it is the photo folder, the app folder or inside wwwroot.

  • If your reverse proxy limits request bodies (nginx: client_max_body_size), allow at least 100 MB so saving a note or activity with several photos works.

Why SQLite?

I think SQLite is a good fit for this app for a couple of reasons:

  1. How many contacts do you have on your phone? Hundreds? Or maybe a few thousands? That's basically nothing. Even for a SQLite database.
  2. Super easy to make a backup. Just copy the people.db somewhere (like your Dropbox/OneDrive/GoogleDrive). You're done. That makes automation of the backups simple as hell. While the app is running, sqlite3 people.db ".backup 'people-backup.db'" gives you a consistent copy. Don't forget the photo and attachment folders.
  3. No additional installations needed. With SQLite, the app will create and maintain your database. No need to setup a DBMS. Just setup the app.

Running the tests

dotnet test runs the unit tests and the UI tests. The UI tests start the app themselves with a temporary database and a test login, so neither Keycloak nor your local people.db is involved. The first run downloads Playwright's Chromium (about 150 MB, cached in ~/Library/Caches/ms-playwright on macOS).

  • dotnet test PeopleIKnow.UITests runs only the UI tests. They cover phone (390×844) and desktop (1280×800) screens in light and dark mode, including checks for sideways scrolling, tap target sizes and text contrast.
  • HEADED=1 dotnet test PeopleIKnow.UITests shows the browser while the tests run.

Commit checks

The build fails on compiler and analyzer warnings and on badly formatted C# code (rules in .editorconfig). dotnet format fixes the formatting.

The repository is public, so .githooks/ holds git hooks that keep private things out of it. They also report formatting problems and failing unit tests before they leave your machine. Turn them on once per clone:

git config core.hooksPath .githooks
  • pre-commit refuses people.db, deploy*.sh, appsettings.Production.json and .superpowers/, and any added line that contains a private term. It also checks that the staged C# files are formatted.
  • commit-msg refuses a Co-Authored-By trailer and messages that contain a private term.
  • pre-push runs the unit tests and stops the push if one fails.

git commit --no-verify and git push --no-verify skip the hooks. The build still enforces the formatting rules.

Private terms are your hostnames, domains and account names, one per line, in .git/info/private-terms. That file is never tracked; without it the private-term check is skipped with a warning.

Project layout

Folder What's in it
PeopleIKnow The ASP.NET Core MVC app: controllers, Razor views, EF Core data access, migrations, resources (English and German)
PeopleIKnow/wwwroot CSS, JS, the self-hosted fonts and the icon sprite (icons.svg)
PeopleIKnow.UnitTests xUnit tests for controllers, repositories and helpers; Conventions checks project-wide rules
PeopleIKnow.UITests Playwright UI tests
keycloak-theme The optional Keycloak login theme, see Give the login page the app's look
.githooks Git hooks for commits and pushes, see Commit checks
docs/superpowers Design documents and implementation plans, e.g. for the current look

The front end is server-rendered: real pages and forms, with a little plain JavaScript on top. It uses Bulma underneath, themed with the app's own design tokens, the fonts Bricolage Grotesque and Public Sans and icons from Lucide.

Something is missing?

Are you missing some kind of feature? You are welcome to create an issue here in the GitHub repo. Let's discuss it and see if it would benefit other people as well.

Or even better: After creating the issue, fork the repo, implement the feature and send me a pull-request. :-)