System Glossary: Milk Men
Document ID: GLOSSARY-001
Version: 1.0.0-DRAFT
Created: 2025-12-26
Governing Document: 0.1.1-PROJECT-CHARTER.md
Purpose: Define all core terms to eliminate ambiguity in implementation
---
Usage Rules
1. No term may be used in code, documentation, or discussion unless defined here
2. Terms are case-sensitive in code; case-insensitive in discussion
3. If a term appears ambiguous, this document is authoritative
4. New terms require glossary update before use
---
1. Domain Layer Terms
These terms describe business concepts independent of implementation.
1.1 Organization
| Attribute | Value |
|---|
| Definition | A distinct business entity that uses the platform; the top-level tenant boundary |
| What it is | A company, team, or business unit with its own members, data, and configuration |
| What it is NOT | A user account; a region; a team within an organization |
| Layer | Domain / Conceptual |
| Database Table | `organizations` |
| Swift Type | `Organization` |
| Cardinality | One user belongs to exactly one organization |
1.2 Vertical
| Attribute | Value |
|---|
| Definition | An industry category that determines default terminology and feature configuration |
| What it is | A preset configuration template (Coffee & Beverage, Food Service, Retail & Wholesale, Custom) |
| What it is NOT | A separate product; a customizable workflow engine; a user-defined category |
| Layer | Domain / Configuration |
| Database Column | `organizations.vertical_id` |
| Swift Type | `VerticalType` (enum) |
| Values | `coffee_beverage`, `food_service`, `retail_wholesale`, `custom` |
1.3 Member
| Attribute | Value |
|---|
| Definition | A user who belongs to an organization with an assigned role |
| What it is | The association between a user account and an organization |
| What it is NOT | The user account itself; an agent record; an invite |
| Layer | Domain / Access Control |
| Database Table | `organization_members` |
| Swift Type | `OrganizationMember` |
1.4 Location
| Attribute | Value |
|---|
| Definition | A physical business establishment that is a current or potential customer |
| What it is | A shop, restaurant, store, or account with geographic coordinates |
| What it is NOT | A user's location; a GPS coordinate without business context; a territory |
| Layer | Domain / Core Entity |
| Database Table | `locations` |
| Swift Type | `Location` |
| Terminology Variants | Shop (Coffee), Restaurant (Food), Account (Retail), Location (Custom) |
1.5 Agent
| Attribute | Value |
|---|
| Definition | A field representative who executes routes, visits locations, and records activities |
| What it is | A sales rep, delivery driver, or field service person with assigned work |
| What it is NOT | A user account (though linked); a software agent; an AI agent |
| Layer | Domain / Core Entity |
| Database Table | `agents` |
| Swift Type | `Agent` |
| Terminology Variants | Agent (Coffee), Driver (Food), Rep (Retail), Agent (Custom) |
1.6 Visit
| Attribute | Value |
|---|
| Definition | A recorded interaction between an agent and a location |
| What it is | A time-bounded activity at a specific location with logged outcomes |
| What it is NOT | A route stop (planned); a location view (passive); a delivery (transaction) |
| Layer | Domain / Core Entity |
| Database Table | `store_visits` |
| Swift Type | `StoreVisit` |
| Terminology Variants | Visit (Coffee), Service Call (Food), Sales Call (Retail), Visit (Custom) |
1.7 Route
| Attribute | Value |
|---|
| Definition | An ordered sequence of locations to be visited by an agent |
| What it is | A planned itinerary with optimized stop order and navigation |
| What it is NOT | A territory (boundary); a visit log (historical); a delivery schedule |
| Layer | Domain / Core Entity |
| Database Table | `routes` |
| Swift Type | `Route` |
1.8 Territory
| Attribute | Value |
|---|
| Definition | A geographic boundary defining an agent's assigned coverage area |
| What it is | A polygon on a map with an assigned agent |
| What it is NOT | A region (administrative); a route (itinerary); a list of locations |
| Layer | Domain / Geographic |
| Database Table | `territories` |
| Swift Type | `Territory` |
1.9 Region
| Attribute | Value |
|---|
| Definition | An administrative grouping of locations, agents, and territories |
| What it is | A named area (e.g., "New York", "California") for organizational filtering |
| What it is NOT | A territory (agent-assigned); a timezone; a country |
| Layer | Domain / Administrative |
| Database Table | `regions` |
| Swift Type | `Region` |
1.10 Invite
| Attribute | Value |
|---|
| Definition | A token that allows a new user to join an organization |
| What it is | A code (email or link-based) with role assignment and expiration |
| What it is NOT | A membership; a user account; a permanent access token |
| Layer | Domain / Access Control |
| Database Table | `invites` |
| Swift Type | `Invite` |
1.11 Partner
| Attribute | Value |
|---|
| Definition | A location that has been converted to an active customer |
| What it is | A location with `is_partner = true` indicating active business relationship |
| What it is NOT | A separate entity from Location; a different table; a user |
| Layer | Domain / Status |
| Database Column | `locations.is_partner` |
| Swift Property | `Location.isPartner` |
1.12 Lead
| Attribute | Value |
|---|
| Definition | A location in early sales pipeline stages |
| What it is | A location with stage in [prospecting, contacted, qualified] |
| What it is NOT | A separate entity; a contact person; an opportunity |
| Layer | Domain / Status |
| Database Column | `locations.stage` |
| Swift Property | `Location.stage` |
---
2. Architectural Layer Terms
These terms describe system structure and components.
2.1 Tenant
| Attribute | Value |
|---|
| Definition | The data isolation boundary; synonymous with Organization in this system |
| What it is | The unit of data separation enforced by RLS |
| What it is NOT | A physical database; a schema; a deployment |
| Layer | Architecture / Multi-tenancy |
| Enforcement | Row Level Security via `organization_id` |
2.2 Context (Singleton)
| Attribute | Value |
|---|
| Definition | A shared, observable state container accessible throughout the app |
| What it is | A @MainActor @Observable singleton holding current session state |
| What it is NOT | A service (has no business logic); a view model; a database |
| Layer | Architecture / State Management |
| Examples | `OrganizationContext`, `RegionContext` |
2.3 Service
| Attribute | Value |
|---|
| Definition | A class that encapsulates business logic and data operations |
| What it is | An @Observable class with async methods that interact with Supabase |
| What it is NOT | A singleton (may be instantiated); a context (has logic); a model |
| Layer | Architecture / Business Logic |
| Examples | `OrganizationService`, `LocationService`, `GooglePlacesService` |
2.4 Model
| Attribute | Value |
|---|
| Definition | A data structure representing a domain entity |
| What it is | A Codable struct with properties matching database schema |
| What it is NOT | A service (no methods beyond computed properties); a view model |
| Layer | Architecture / Data |
| Location | `Milk Men/Models/` |
2.5 Edge Function
| Attribute | Value |
|---|
| Definition | A serverless function running on Supabase infrastructure |
| What it is | TypeScript code executing server-side with access to secrets |
| What it is NOT | A Swift function; a stored procedure; a webhook |
| Layer | Architecture / Backend |
| Location | `supabase/functions/` |
2.6 RLS (Row Level Security)
| Attribute | Value |
|---|
| Definition | PostgreSQL policy that filters data access at the database level |
| What it is | SQL policies attached to tables controlling SELECT/INSERT/UPDATE/DELETE |
| What it is NOT | Application-level filtering; an API middleware; encryption |
| Layer | Architecture / Security |
---
3. Runtime Layer Terms
These terms describe runtime concepts and behaviors.
3.1 Demo Mode
| Attribute | Value |
|---|
| Definition | A special app state using local sample data without authentication |
| What it is | A boolean flag enabling offline exploration with fake data |
| What it is NOT | A test environment; a sandbox; a trial period |
| Layer | Runtime / Mode |
| Swift Property | `AuthService.isDemoMode` |
3.2 Onboarding
| Attribute | Value |
|---|
| Definition | The multi-step flow for new users to create or join an organization |
| What it is | A modal flow: Choice → Vertical → Setup → Invite |
| What it is NOT | Account creation (happens before); a tutorial; settings |
| Layer | Runtime / Flow |
| Swift View | `OnboardingContainerView` |
3.3 Enrichment
| Attribute | Value |
|---|
| Definition | The process of augmenting a Location with Google Places data |
| What it is | Fetching and storing photos, ratings, hours, reviews from Google |
| What it is NOT | Location creation; data import; manual editing |
| Layer | Runtime / Process |
| Swift Method | `GooglePlacesService.enrichLocation()` |
3.4 Sync
| Attribute | Value |
|---|
| Definition | The process of reconciling local (offline) data with server state |
| What it is | Uploading queued changes and downloading updates |
| What it is NOT | Real-time updates; cache refresh; backup |
| Layer | Runtime / Process |
| Swift Service | `SyncService` |
---
4. External System Terms
4.1 Google Place
| Attribute | Value |
|---|
| Definition | A business entity in Google's Places database |
| What it is | External data with place_id, name, coordinates, photos, reviews |
| What it is NOT | A Location in our system (until imported); a Google account |
| Layer | External / Google |
| Swift Type | `GooglePlaceResult`, `GooglePlaceDetails` |
4.2 Square POS
| Attribute | Value |
|---|
| Definition | Square's Point of Sale application for payment processing |
| What it is | External app launched via URL scheme to process transactions |
| What it is NOT | Our payment system; a Square account; Square's API directly |
| Layer | External / Payments |
4.3 Supabase
| Attribute | Value |
|---|
| Definition | The backend-as-a-service platform providing database, auth, and functions |
| What it is | PostgreSQL + Auth + Edge Functions + Storage |
| What it is NOT | A generic database; Firebase; our code |
| Layer | External / Backend |
---
5. Terminology System Terms
5.1 Terminology Key
| Attribute | Value |
|---|
| Definition | A standardized key for retrieving vertical-specific display text |
| What it is | An enum case (e.g., `.location`, `.visit`, `.agent`) |
| What it is NOT | A localization key; a database column; a variable name |
| Layer | System / Configuration |
| Swift Type | `TerminologyKey` |
5.2 Terminology Provider
| Attribute | Value |
|---|
| Definition | The singleton that resolves terminology keys to display strings |
| What it is | A service mapping keys to vertical-specific terms |
| What it is NOT | Localization (i18n); a dictionary; a model |
| Layer | System / Configuration |
| Swift Type | `TerminologyProvider` |
---
Revision History
| Version | Date | Changes |
|---|
| 1.0.0-DRAFT | 2025-12-26 | Initial glossary with 25 terms |
---
All code, documentation, and discussion must use terms as defined in this glossary.