Jerald.Atlas — System Documentation

1. What is Jerald.Atlas?

Atlas is a simple system for organizing everything that matters. It connects real-world physical locations and items with supporting notes, tasks, and digital links across six primary entity tables:

AREAS (`areas`)

Physical spaces and locations (`A01.01` – `A01.99`)

OBJECTS (`objects`)

Physical items inside spaces (`O01.01` – `O01.99`)

NOTES (`notes`)

Knowledge, observations, ideas (`N01.01` – `N01.99`)

TASKS (`tasks`)

Actionable work items (`T01.01` – `T01.99`)

DIGITAL ITEMS (`digital_items`)

Websites, files, spreadsheets (`D01.01` – `D01.99`)

ID REGISTRY & SEQUENCES

Global tracking via `atlas_id_registry` & `atlas_id_sequence`

The Goal: Know where things are, know what they are, and know what needs to happen next.

2. Relational Architecture

Atlas maps records back to real-world context using optional foreign keys (`area_id`, `object_id`) pointing to parent records:

AREA → OBJECT → NOTES / TASKS / DIGITAL ITEMS

A01.03 — Kitchen (areas.id = 2)

│

├── O01.02 — Dishes (objects.id = 2, area_id = 2)

├── Note [N01.02] — Black dishes in cabinet (notes.area_id = 2)

└── Task [T01.02] — Organize closet (tasks.area_id = 2)

│

└── O01.05 — Stove (objects.id = 5, area_id = 2)

├── Note [N01.03] — Stove uses natural gas

└── Digital Item [D01.02] — Laptop Documentation (digital_items.object_id = 8)

Notes, Tasks, and Digital Items can belong to an Object, directly to an Area, or exist as standalone global items (`area_id = NULL`, `object_id = NULL`).

3. Areas (`areas`)

An Area represents a physical location (e.g., Living Room, Bedroom, Garage, Office, Kitchen).

A01.03 — Kitchen A01.04 — Living Room A01.05 — Bedroom A01.06 — Garage A01.07 — Office

Database Structure (`areas`)

Column	Type	Description
id	bigint(20) PK	Auto-increment primary key
user_id	int(11) FK	Maps to `accounts.id`
atlas_id	varchar(50)	Unique per user (e.g., `A01.03`)
name	varchar(255)	Area name
description	text	Detailed description

4. Objects (`objects`)

An Object represents a physical item inside an area (e.g., Television, Sofa, Tool Cabinet, Desk, Laptop).

LIVE DATABASE EXAMPLES

A01.07 — Office (id = 6)

O01.07 — Desk
Large wooden office desk

O01.08 — Laptop
Primary laptop used for development

5. Notes (`notes`)

Notes store static reference knowledge, titled observations, and structured instructions.

N01.03 • Television Information area_id: 1 | object_id: 4

Television Information

Television is mounted on the main wall. Remote control is normally kept on the coffee table.

6. Tasks (`tasks`)

Tasks represent actionable work items. Priorities and statuses are constrained strictly by application logic:

T01.05 • TASK

Update Laptop

Install pending operating system and application updates.

priority: high

Area FK: 4 Object FK: 8 Status: in_progress Due: 2026-08-30

ALLOWED PRIORITIES

low • normal • high • urgent

ALLOWED STATUSES

open • in_progress • completed

7. Digital Items (`digital_items`)

Attach manuals, receipts, spreadsheets, web links, and documentation to physical items or store them globally.

D01.02 Laptop Documentation Documentation and support information for the laptop.

type: document example.com/...

D01.04 House Inventory Spreadsheet Global house inventory (area_id = NULL, object_id = NULL)

type: spreadsheet

8. ID Registry & Sequence Mechanics

Atlas generates immutable, user-isolated human-readable IDs using two dedicated tables: `atlas_id_sequence` and `atlas_id_registry`.

Entity Prefixes & Sequence State

AREAPrefix: A

OBJECTPrefix: O

NOTEPrefix: N

TASKPrefix: T

DIGITALPrefix: D

1. `atlas_id_sequence`: Tracks the `next_sequence` integer per `(user_id, entity_type)` pair. For example, for `user_id = 1` and `entity_type = 'digital_item'`, `next_sequence` is currently 7.

2. `atlas_id_registry`: Audit log ensuring an ID (e.g., `A01.03`) is reserved permanently and can never be reassigned even if the original record is deleted.

9. Multi-Tenancy & Security Rules

Atlas enforces complete tenant separation at the database level using composite unique indexes and strict SQL scoping.

REQUIRED CLAUSE ON EVERY SQL QUERY:

SELECT * FROM objects WHERE id = ? AND user_id = ?;

Composite Index Protection: Tables enforce unique constraints like `uq_areas_user_atlas_id (user_id, atlas_id)`. Two users can both own `A01.01` without data leakage.
Foreign Key Integrity: FKs bind `user_id` directly to `accounts.id` with `ON DELETE CASCADE`.

10. Recommended Workflow

01
Create the Area INSERT INTO `areas` → Generates `A01.03` A01.03 — Kitchen
02
Create the Object INSERT INTO `objects` WITH `area_id = 2` → Generates `O01.05` O01.05 — Stove
03
Add Notes INSERT INTO `notes` WITH `area_id = 2`, `object_id = 5` Title: "Stove Information"
04
Add Tasks INSERT INTO `tasks` WITH priority='high', status='open' Schedule annual maintenance
05
Add Digital Items INSERT INTO `digital_items` WITH type='document' Upload or link manual PDF URL

11. The Rule of Atlas

Areas (`areas`) tell you where.
Objects (`objects`) tell you what.
Notes (`notes`) tell you what you know.
Tasks (`tasks`) tell you what to do.
Digital Items (`digital_items`) tell you where supporting information lives.

Quick Reference

Entity	Database Table	ID Prefix	Key Columns
Area	`areas`	A01.XX	name, description
Object	`objects`	O01.XX	area_id (FK), name, description
Note	`notes`	N01.XX	area_id (FK), object_id (FK), title, content
Task	`tasks`	T01.XX	status, priority, due_date, completed_at
Digital Item	`digital_items`	D01.XX	type, url, description
Account	`accounts`	—	id, username, email, role, approved

Jerald.Atlas /

Jerald.Atlas Documentation