# Project pack: Monica @ 6e6ec21

Facts about **Monica** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Monica is a private address book with a memory. Keep notes about friends and family: how you met, their children's names, their pets, money you lent and what you talked about last time. It reminds you of birthdays and other important dates by email or Telegram, and has a journal for your own life. It is for your eyes only, never a social network, and it runs on your own server. The pinned code is Monica's new version, still marked beta upstream.

## Version and source
- Repository: https://github.com/monicahq/monica
- Pinned commit: `6e6ec217457e946e330ba7cd3b28107f4332c7b1`. Use exactly this version.
- Get it: `git clone https://github.com/monicahq/monica monica && cd monica && git checkout 6e6ec217457e946e330ba7cd3b28107f4332c7b1`
- Or download a zip: https://github.com/monicahq/monica/archive/6e6ec217457e946e330ba7cd3b28107f4332c7b1.zip
- Official docs: https://docs.monicahq.com
- Licence: **AGPL-3.0-or-later**. Free to use and change. If you run a changed version that other people use over the internet (not just you or your household), you must offer them your source code under the same licence. Private use has no extra obligations.

## Running it
- Easiest: git clone https://github.com/monicahq/monica.git && cd monica && docker build -t monica-next -f scripts/docker/Dockerfile . && docker run --name monica -p 8080:80 monica-next # then open http://localhost:8080 and register; save the APP_KEY printed in the log. # Add a volume for the database and storage before relying on it for real data.
- Needs: Docker, or PHP 8.3+, Composer, Node.js and Yarn, A database (SQLite is the default; MariaDB, MySQL or PostgreSQL also work)
- Develop: `./sail-init.sh && cp .env.example.sail .env && ./sail up -d && ./sail artisan key:generate && ./sail artisan monica:setup && ./sail yarn install && ./sail yarn dev`
- Test: `yarn test   # migrates a testing database, then runs phpunit, phpstan and psalm`
- Check/lint: `yarn lint && vendor/bin/pint --test`
- Stack: php, javascript, vue (Laravel 12, Inertia.js, Vue 3, Tailwind CSS, Laravel Jetstream, Laravel Scout). Difficulty for a non-developer with an AI: **moderate**. A standard Laravel app. Code is grouped by feature in app/Domains/ (Contact, Vault, Settings), each with Services, Web controllers and view helpers, and Vue pages in resources/js/Pages/. Much of the contact page layout is configurable in settings. This branch is upstream's beta; the stable 4.x line lives on a separate branch.

## Customisation points (settings → extend → code)
- **personalise-contact-page** [settings]: Choose which sections appear on a contact page, e.g. hide Loans, add Pets or Life events. → `Settings → Personalize → templates and modules (app/Domains/Settings/ManageTemplates, ManageModules)`
- **lists-and-types** [settings]: Make the options fit your family and culture. → `Settings → Personalize (genders, pronouns, relationship types, gift occasions, call reasons, currencies, religions)`
- **vaults-and-users** [settings]: Separate vaults for family and friends, and invite a partner to share one. → `Vaults and Settings → Users (app/Domains/Vault/ManageVault, app/Domains/Settings/ManageUsers)`
- **reminder-channels** [settings]: Get reminders by email or Telegram at the time of day you choose. → `Settings → Notifications (app/Domains/Settings/ManageNotificationChannels)`
- **carddav** [extend]: Sync contacts and birthdays with your phone's address book and calendar. → `CardDAV/CalDAV at /dav (app/Domains/Contact/Dav/), vCard import and export`
- **api** [extend]: Small scripts and integrations. The beta API is limited, so check routes/api.php first. → `REST API with Sanctum tokens (routes/api.php; currently users and vaults only)`
- **contact-features** [code]: New sections or behaviour on a contact page. → `app/Domains/Contact/Manage*/ (Services, Web/Controllers, Web/ViewHelpers) + resources/js/Pages/Vault/Contact/`
- **vault-pages** [code]: New dashboards, reports or journal features. → `app/Domains/Vault/ (e.g. ManageJournals, ManageReports) + resources/js/Pages/Vault/ (Dashboard, Journal, Reports)`
- **text-and-emails** [code]: Wording and the look of reminder emails. → `lang/*.json (one file per language), resources/views/emails/`

## Must keep working
- Existing contacts, notes, photos and documents. Back up the database and storage folder first.
- APP_KEY. Changing or losing it makes encrypted data unreadable.
- Vault permissions. People invited to one vault must not see another.
- Database changes need a Laravel migration in database/migrations/.
- Reminder scheduling (app/Domains/Contact/ManageReminders) and the queue and cron workers that send them.

## Staying updatable
Contact-page templates, modules, custom lists, notification channels and CardDAV cover most personal needs without a fork. This branch is in beta, so pin a commit and expect database changes between updates.

## Data, costs and safety
- Personal data: **yes**. Stored in: The database (SQLite file database/database.sqlite by default) plus uploaded photos and documents in storage/. This is sensitive personal data about other people. Back up the database and storage folder, keep APP_KEY safe, and test a restore before upgrading or changing code. The beta can change its database between versions.
- Service: Email (SMTP) (optional, free with most providers): Birthday and reminder emails, and inviting other users.
- Service: Telegram bot (optional, free): Reminders sent to Telegram instead of, or as well as, email.
- Service: Meilisearch or Typesense (optional, free (self-hosted)): Faster search for large address books. The database works for most people.
- Service: LocationIQ / Mapbox (optional, free tier): Maps and address lookup for contacts' addresses.
- Setting `APP_KEY` (**secret**: the person enters it themselves, never in chat): Encryption key. Generated on first start in Docker; save it, as it is needed to keep your data readable. Never paste it into an AI chat.
- Setting `APP_URL`: The address you open Monica at (needed for links in emails).
- Setting `DB_CONNECTION`: Database type (sqlite by default, or mysql, mariadb, pgsql).
- Setting `APP_DISABLE_SIGNUP`: Set to true after creating your account so strangers can't register.
- Setting `MAIL_MAILER`: How emails are sent (smtp for real emails; log just writes them to the log). Set MAIL_HOST, MAIL_USERNAME and MAIL_PASSWORD too.
- Setting `MAIL_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password for your email account. Never paste it into an AI chat.
- Setting `TELEGRAM_BOT_TOKEN` (**secret**: the person enters it themselves, never in chat): Only for Telegram reminders (with TELEGRAM_BOT_URL and TELEGRAM_BOT_WEBHOOK_URL).
- Setting `DEFAULT_STORAGE_LIMIT`: Upload space per account in MB (default 50).
- Monica holds private details about other people. Keep it on your own server, use HTTPS, and set APP_DISABLE_SIGNUP=true.
- Upstream marks this branch as beta. Back up before every update.
- Never paste APP_KEY, mail passwords or the Telegram token into an AI chat.

---

# Customising Monica

Monica is a standard Laravel app with Vue pages (via Inertia). **Much of what you see is configurable in Settings**, especially which sections appear on a contact page. Exhaust levels 1 and 2 before touching code.

> The pinned commit is upstream's **beta** (the next major version). The stable 4.x line is on the `4.x` branch and the official `monica` Docker image. Pin a commit and back up before every update.

## Level 1: Settings (no code)
- **Contact page layout:** Settings → Personalize → *templates* and *modules*. Choose which modules (notes, important dates, pets, loans, life events and more) appear, and on which tab.
- **Your own lists:** Settings → Personalize: genders, pronouns, relationship types, address types, contact information types, gift occasions, call reasons, religions, pet categories, currencies, post (journal) templates.
- **Vaults and people:** create separate vaults (e.g. Family, Friends) and invite a partner in Settings → Users.
- **Reminders:** Settings → Notifications. Add email addresses or Telegram and pick the time of day reminders are sent. Use *Send test* to check.
- **Preferences:** name order, date format, time zone, language (Settings → Preferences).
- **Sign-ups:** `APP_DISABLE_SIGNUP=true` once your account exists.

## Level 2: Extend (no fork)
- **CardDAV/CalDAV** at `/dav` (with `/.well-known/carddav` and `/.well-known/caldav` redirects): sync contacts and birthdays with your phone. Code in `app/Domains/Contact/Dav/`.
- **vCard import and export** of contacts.
- **Telegram reminders:** set `TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_URL` and `TELEGRAM_BOT_WEBHOOK_URL`, then register the webhook (see the developer docs at docs.monicahq.com).
- **REST API** with Sanctum tokens (`routes/api.php`). In this beta it only covers users and vaults, so most automations need CardDAV or code.

## Level 3: Code
Code is grouped by feature in `app/Domains/`. Each feature has `Services/` (logic), `Web/Controllers/` and `Web/ViewHelpers/` (data for the Vue page).

| Change | Where |
|---|---|
| New section on a contact page | `app/Domains/Contact/Manage<Thing>/` + `resources/js/Pages/Vault/Contact/` |
| Vault pages (dashboard, journal, reports) | `app/Domains/Vault/` (e.g. `ManageJournals`, `ManageReports`) + `resources/js/Pages/Vault/` |
| Settings screens | `app/Domains/Settings/` + `resources/js/Pages/Settings/` |
| Shared Vue components and layout | `resources/js/Components/`, `resources/js/Layouts/` |
| Routes | `routes/web.php`, `routes/api.php` |
| New data | `database/migrations/` + models in `app/Models/` |
| Text | `lang/en.json` (other languages in `lang/*.json`) |
| Reminder emails | `resources/views/emails/` |
| Reminder scheduling | `app/Domains/Contact/ManageReminders/` |

## Running locally
- **Just use it (beta):**
  1. `git clone https://github.com/monicahq/monica.git && cd monica`
  2. `docker build -t monica-next -f scripts/docker/Dockerfile .`
  3. `docker run --name monica -p 8080:80 monica-next`, then open http://localhost:8080.
  4. Save the `APP_KEY` printed in the log. Add volumes for the database and `storage/` before real use.
- **Develop (Laravel Sail):**
  1. `./sail-init.sh` (installs Composer packages and creates the `sail` link).
  2. `cp .env.example.sail .env`, then `./sail up -d`.
  3. `./sail artisan key:generate` and `./sail artisan monica:setup`.
  4. `./sail yarn install` and `./sail yarn dev`, then open http://localhost.
- **Check:** `yarn test` (PHPUnit, PHPStan and Psalm), `yarn lint`, `vendor/bin/pint --test`.

## Pitfalls
- Back up the database **and** `storage/` before updates or code changes. The beta can change its database.
- Keep `APP_KEY` safe. Without it, encrypted data cannot be read.
- Reminders need the queue worker and the scheduler (`php artisan schedule:run` every minute). Without them nothing is sent.
- Every query must stay inside the current vault. Use the existing services, which check permissions.
- Don't build on the API for big features yet; it is very small in this beta.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/monica/6e6ec21/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/monica/6e6ec21/SKILL.md)