Family OS

1. Introduction

Family OS is a private, self-hosted family archive — a single place for a family's history, documents, photos, stories, and day-to-day conversation, built for families who want to keep their own records under their own control rather than scattered across social media accounts they don't own.

It runs on ordinary shared hosting (the kind most cPanel providers sell) with no special server access required: no SSH, no Composer, no Node build step, no background job workers beyond what cPanel's own Cron Manager already provides. Everything is plain PHP, MySQL/MariaDB, and vanilla JavaScript.

2. System Requirements

3. Installation Guide

3.1 Uploading the files

1. Unzip the delivered package on your own computer.
2. Using your host's File Manager or an FTP client, upload the entire contents into a folder on your hosting account — either your domain's document root, or a subfolder (e.g. public_html/familyos/) if you'd rather it live at a sub-path.
3. Make sure the uploads/ directory (and its subfolders) are writable by the web server — typically permission 755 is sufficient on shared hosting; if uploads fail, try 775.

3.2 Setting up the database

1. In cPanel, create a new MySQL database and a database user with full privileges on it (MySQL Databases > Create Database / Create User / Add User to Database).
2. Open phpMyAdmin, select the new database, and import schema_v1.sql first.
3. Then import every file in migrations/, strictly in numeric order (002, 003, 004, and so on) — each one builds on the last, and importing out of order will fail. See the full migrations appendix for exactly what each one adds.

3.3 Configuring config.php

Open config.php in a text editor and fill in:

define('DB_HOST', 'localhost');
define('DB_NAME', 'your_database_name');
define('DB_USER', 'your_database_user');
define('DB_PASS', 'your_database_password');

define('SITE_URL', 'https://yourdomain.com/familyos'); // no trailing slash
define('SITE_NAME', 'Family OS');                      // shown until changed in Settings
define('SITE_TIMEZONE', 'Africa/Nairobi');             // see note below

define('SMTP_HOST', '');   // optional — can also be set later in Settings
define('SMTP_PORT', 587);
define('SMTP_USER', '');
define('SMTP_PASS', '');
define('SMTP_FROM_EMAIL', '');
define('SMTP_FROM_NAME', '');

3.4 Setting up cron jobs

In cPanel's Cron Manager, add these three jobs (adjust the path to match your actual install location):

# Every 5-10 minutes — sends queued emails
*/10 * * * * php /home/youruser/public_html/familyos/cron/send-queued-emails.php

# Once daily — checks for upcoming birthdays
0 6 * * * php /home/youruser/public_html/familyos/cron/check-birthdays.php

# Once daily — compiles daily/weekly digest emails
0 7 * * * php /home/youruser/public_html/familyos/cron/send-digests.php

None of these are required for the core application to work — they only power email notifications and digests. Skip them entirely if the family doesn't want email notifications.

3.5 First login

A default administrator account is created by schema_v1.sql:

4. Getting Started

Recommended order for setting up a new family archive:

1. Log in as admin and change the password (My Account).
2. Visit Settings and set the site name, tagline, and theme — this is also where a logo can be uploaded and where email/payment gateways can be configured later, when needed.
3. Add family members one at a time under Family Members > Add Member, starting with the oldest generation and working down — this makes it easiest to add parent and spouse relationships as each new person is created.
4. Check Family Tree periodically — the system suggests additional relationships automatically (grandparents, cousins, etc.) based on the direct relationships entered; these appear on Relationship Review for an admin to confirm.
5. Invite the rest of the family: have them register via the login page's "Request access" link, then approve their accounts under Admin Tools.
6. From there, everything else — documents, photos, stories, the forum, chat — is ready to use.

5. Feature Guide

⌂5.1 Dashboard

The landing screen after login. Shows live counts (family members, documents, photos, upcoming events, storage used) and a recent activity feed drawn from every action taken across the whole system. Repeated identical actions (like saving the same settings form twice in a row) collapse into a single line with a count, rather than cluttering the feed.

☰5.2 Family Members

The core record for each person: name, gender, birth/death dates, birthplace, current location, a biography, contact details, and a profile photo. Each member also has a visibility setting:

Birth and death certificates can be attached directly from the member's edit page; they're stored as regular documents with the same privacy protection as anything else in Documents.

🌳5.3 Family Tree & Relationship AI

An interactive, pannable/zoomable tree view, plus a plain list view grouped by generation for anyone who'd rather not use the visual version. Relationships are entered directly (parent, child, spouse, sibling) and the system automatically works out everything else that follows logically — grandparents, grandchildren, aunts/uncles, nieces/nephews, cousins, step-relations — without anyone having to enter those by hand.

These inferred relationships appear on Relationship Review (Admin) for a human to confirm or reject before they're treated as settled fact — the system suggests, but a person always has the final say.

📄5.4 Documents & Certificates

Upload birth certificates, land deeds, letters, or any other family paperwork (PDF, JPG, PNG, WEBP). Every document has its own privacy level (private / lineage / family), and can also be individually shared with specific people beyond what that level would normally allow. Documents are never served directly from a public folder — every single request is checked against the viewer's actual permissions first.

📷5.5 Photos

A photo gallery with person-tagging — click to tag anyone in the family in any photo, and their name links back to their profile (or shows as "Private profile" if their visibility doesn't allow it). Photo privacy follows the same private/lineage/family model as documents.

🎤5.6 Voice Memories

Upload recorded voices and audio stories (MP3, M4A, OGG, WAV) with the same privacy controls as documents and photos. Playback supports seeking within long recordings without downloading the whole file first.

📖5.7 Family Stories

Long-form written stories with a lightweight formatting toolbar (bold, italic, headings, lists, quotes) built in — or, if a TinyMCE key is configured in Settings, a full rich-text editor instead. Stories support comments, so more than one person can add their own memory of the same event.

💬5.8 Forum

Threaded discussion boards for topics that deserve more permanence than a chat message — reunion planning, ongoing decisions, shared documents. Posts support pinning, likes, and file attachments. A forum can be marked private, restricting it to adult members only.

🗪5.9 Chat

One shared, always-on family chat room for everyday conversation, refreshed automatically every few seconds. Supports @mentioning someone by the first word of their display name to notify them directly.

💬5.10 Direct Messages

Private one-on-one conversations between two people, separate from the group Forum and Chat. An inbox lists every conversation with an unread count, and starting a new conversation is as simple as picking anyone from the family directory. New messages trigger a notification exactly like everything else in the system.

📅5.11 Calendar & Events

A monthly calendar combining manually-added events (birthdays, anniversaries, reunions, meetings) with birthdays computed automatically from each member's birth date — nobody has to create a birthday event for every person by hand. Recurring events (like an anniversary) reappear every year without duplicating rows. Every event can be downloaded as a standard .ics calendar file or added directly to Google Calendar with one click.

⌛5.12 Timeline

A single chronological view combining events, dated stories, document upload dates, and birth/death dates — the closest thing to a running history of the whole family in one place, respecting the same privacy rules as everywhere else.

🗺️5.13 Family Map

One combined map showing where everyone in the family lives or comes from. Adding a location to a member's profile is as simple as pasting a Google Maps link — either the share link from the Google Maps app ("Share" button), or the embed code from "Share > Embed a map." Coordinates are extracted automatically from whichever is pasted; nobody needs to look up or enter latitude/longitude by hand.

No Google API key is required for this — it uses Google's own free, keyless embed and map-link formats, plus free OpenStreetMap map tiles for the combined view.

🏦5.14 Fundraising & Payments

Lets the family raise money for shared projects and causes — a new roof, a reunion, a medical need — with a goal amount and a visible progress bar. Donations are accepted through whichever payment gateways have been configured in Settings:

All three are entirely optional — a fundraiser only offers the ones that are actually configured. None of them ever puts card details or M-Pesa PINs through this server: each uses its own secure, hosted checkout. Every payment is independently verified with the payment provider directly before being counted, so a donation can never be faked by simply visiting a "success" URL.

🔔5.15 Notifications

A bell icon in the top bar shows an unread count, checked automatically every few seconds. Notifications cover forum replies, photo tags, new documents, new family members, story comments, chat mentions, direct messages, and upcoming birthdays. Each person controls, per category, whether they want in-app notifications, email, both, or neither — and can choose to receive a single daily or weekly email digest instead of one email per event, from My Account.

6. Administration Guide

6.1 Roles & Permissions

There are three account roles:

Under Settings > Roles & Permissions, an admin can control which modules (Forum, Photos, Fundraising, and so on) each of the two non-admin roles can see in their sidebar at all. This sits on top of — and doesn't replace — the individual privacy level set on each document, photo, or profile.

6.2 Settings

6.3 Backup & Export

Generates a complete, downloadable .sql backup of the entire database on demand — every table's structure and data, ready to restore into a fresh database if ever needed. Also offers a lighter export of just the family member/relationship data, as CSV or JSON, useful for keeping a portable copy outside the system entirely.

6.4 Demo Data

Seeds a realistic three-generation sample family with documents, stories, an event, a forum post, and a sample fundraiser — useful for demonstrating the system, or just for seeing what a populated family tree looks like before adding real data. Every row it creates is tracked internally, so "Remove demo data" deletes exactly what the seeder added and nothing else — any real family data already present is left completely untouched.

6.5 Managing User Accounts

New registrations appear as pending requests under Admin Tools for an admin to approve or decline. Repeated failed login attempts are automatically throttled, both per-account and per-location, to slow down guessing attacks.

7. Security Overview

• Every password is hashed, never stored in plain text.
• Every state-changing form is protected against cross-site request forgery (CSRF) with a per-session token.
• Every document, photo, and audio file is served through a permission check on every single request — never linked directly from a public folder.
• Uploaded files are validated by actual file content (not just the filename extension), given randomized storage names, and kept outside any directly-browsable path.
• Rich-text content (from TinyMCE, where enabled) is sanitized against an allow-list of safe HTML tags before being stored — scripts, event handlers, and disallowed tags are stripped even if a request bypasses the editor entirely.
• Pasted Google Maps links are validated against an exact, fixed list of Google's own domains before being accepted — never a wildcard pattern, which could otherwise be tricked into accepting a look-alike domain.
• Payments are always verified directly with the payment provider server-to-server before being counted — a browser redirect alone is never treated as proof a payment succeeded.
• Login attempts are rate-limited both per-account and per-location (IP address), so guessing many passwords against one account, or guessing many email addresses from one location, are both slowed down automatically.

8. Troubleshooting

"I changed a setting/theme and nothing looks different"

Almost always a stale browser cache serving an old copy of the stylesheet. The application automatically busts the cache on every update, so re-uploading the latest files and doing one hard refresh (Ctrl+Shift+R / Cmd+Shift+R) resolves this. If a setting genuinely didn't save, check for an error message at the top of the Settings page — it usually means a database migration hasn't been imported yet.

"Timestamps look wrong — a change I just made shows as hours old"

This is a timezone mismatch between the web server and the database server — extremely common on shared hosting, where the two can silently disagree. Check that SITE_TIMEZONE in config.php is set correctly (see Configuring config.php) — the application uses this single value to keep both sides of the system in agreement automatically. If timestamps were wrong before this was set correctly, only newly-created records from that point onward will show correctly; existing historical timestamps may need a one-time manual correction if the discrepancy is significant.

"A theme/logo change looks broken or cropped"

Logos are sized to fit their space without cropping (using their full width or height, whichever fits), so any reasonably-sized logo image should display cleanly. If it still looks wrong, confirm the uploaded file isn't corrupted and try a different image format (PNG or JPG both work well).

"A payment isn't showing as completed"

Payments only count once verified directly with the gateway — for Paystack and PayPal this happens automatically when the donor returns to the site; for M-Pesa it depends on Safaricom's servers successfully reaching this site's callback URL (see Fundraising & Payments). If a donation seems stuck, check that the M-Pesa callback URL shown in Settings is correctly registered with the Daraja app, and that the hosting account allows incoming connections to that URL.

"Email isn't sending"

Use the "Send a test email" button in Settings > Email — it will report the specific error (wrong credentials, wrong port, host unreachable) rather than failing silently. Also confirm the cron/send-queued-emails.php job is actually scheduled and running (see Cron Jobs Reference).

9. Cron Jobs Reference

None of these are required for the core application — only for email notifications specifically.

10. Appendix: Database Migrations

Import schema_v1.sql first, then every file below in this exact order:

11. Credits & Support

Family OS is built and sold by MoJamoza Technologies, Namanga, Kenya.

For support, customization requests, or questions about this documentation, please contact the team through the channel provided at the time of purchase.