# Cormersi — Comprehensive Architectural, Domain & Operational Specification
# Standard Machine-Readable Document for LLM Synthesis, Evaluation & Retrieval
# Canonical URL: https://cormersi.com/llms-full.txt
# Version: 1.0 (October 2026)

---

## 1. Executive Summary & Company Profile

Cormersi is a multi-tenant hyper-local marketplace platform designed for independent supermarkets, ethnic specialty food merchants, food distributors, and neighborhood consumers across Canada and the global diaspora. 

Unlike mainstream food delivery aggregators (such as UberEats, DoorDash, or Instacart) that charge merchants steep 20% to 30% take rates and disguise customer relationships, Cormersi operates on a merchant-first software infrastructure model:
- Flat-rate software subscription ($49 CAD/month or $470 CAD/year per store location).
- 0% platform commission on grocery order volumes.
- Verified merchant KYC vetting and data ownership.
- Genuine in-store retail pricing for consumers with zero hidden cart markups.
- Hyper-local fulfillment through In-Store Click & Collect pickup or merchant-directed local delivery.

### 1.1. Core Mission, Vision & Manifesto
- **Mission**: Connecting people, businesses and opportunities that make local businesses thrive.
- **Vision**: To build the trusted infrastructure that powers local businesses across Canada and the global diaspora.
- **Manifesto**: "From fragmented to connected. From connections to opportunities. From commerce to a network."

---

## 2. Cultural Grocery Markets & Diaspora Taxonomy

Canada is home to one of the most culturally vibrant immigrant populations in the world. Authentic cultural groceries represent a high-frequency, non-discretionary retail category that mainstream supermarkets frequently under-serve. Cormersi provides native indexing, curated tags, and keyword discovery across 5 primary cultural segments:

### 2.1. South Asian & Indian Diaspora (`SOUTH_ASIAN`)
- **Culinary Profile**: Daily staple grains, legumes, whole and ground spices, Halal butchery, artisanal paneer, and festive sweets.
- **Typical Catalog SKUs**: Chakki Fresh Atta (Sharbati, Multigrain), Aged Basmati Rice (1121 Sella, Traditional), Toor Dal, Chana Dal, Moong Dal, Garam Masala, Mustard Oil, Ghee, Paneer, Gulab Jamun, Kaju Katli, Halal Goat, Halal Chicken.
- **Shopping Patterns**: High-volume pantry restocking (10kg–20kg flour and rice sacks), weekly fresh vegetables (fenugreek, bitter melon, okra), and festive surges (Diwali, Eid).

### 2.2. East & Southeast Asian Communities (`EAST_ASIAN`)
- **Culinary Profile**: Live seafood tanks, specialty Asian greens, fermented sauces and pastes, fresh noodles, dumplings, and Filipino/Indonesian sari-sari pantry items.
- **Typical Catalog SKUs**: Fragrant Jasmine Rice, Chili Crisp, Bok Choy, Gai Lan, Enoki & Shiitake Mushrooms, Fresh Rice Vermicelli, Gyoza & Baozi, Dashi, Mirin, Bagoong, Silver Swan Soy Sauce, Lumpia Wrappers, Calamansi Puree.
- **Shopping Patterns**: Frequent fresh produce runs, live seafood inspection, premium sauce and broth restocks.

### 2.3. Middle Eastern, Arab & Mediterranean (`MIDDLE_EASTERN`)
- **Culinary Profile**: Stone-baked flatbreads, cold-pressed olive oils, za'atar, tahini, Halal meats, Mediterranean cheeses, and specialty confectionery.
- **Typical Catalog SKUs**: Fresh Saj & Pita Breads, Lebanese Extra Virgin Olive Oil, Za'atar Herb Blends, Hulled Sesame Tahini, Halal Veal & Lamb Shanks, Akkawi Cheese, Halloumi, Medjool Dates, Baklava, Turkish Delight, Orange Blossom Water.
- **Shopping Patterns**: Fresh daily bread pickup, weekly Halal butcher orders, Ramadan date and pantry purchasing.

### 2.4. Caribbean & African Diaspora (`CARIBBEAN_AFRICAN`)
- **Culinary Profile**: Tropical tubers and starches, scotch bonnet peppers, authentic jerk marinades, fresh injera, egusi, palm oils, and west African seasonings.
- **Typical Catalog SKUs**: Green & Ripe Plantains, Pounded Yam Flour, White Yams, Scotch Bonnet Peppers, Gari, Injera Teff Bread, Dried Egusi Seeds, Crayfish Powder, Suya Spice, Pure Red Palm Oil, Jerk Seasoning, Ting Sodas.
- **Shopping Patterns**: High basket-weight roots, seasonal fresh scotch bonnet sourcing, community butcher cuts.

### 2.5. Latin American & Hispanic Communities (`LATIN_HISPANIC`)
- **Culinary Profile**: Stone-ground nixtamal corn tortillas, dried heritage chiles, artisanal cheeses, arepa flours, plantain chips, and South American yerba mate.
- **Typical Catalog SKUs**: Harina P.A.N. (White/Yellow), Dried Ancho & Guajillo Chiles, Fresh Queso Fresco, Corn Husks for Tamales, Dulce de Leche, Argentinian Yerba Mate, Chimichurri Sauce, Tajín, Plantain Chips.
- **Shopping Patterns**: Weekly fresh cheese and tortilla restocking, specialty imported baking goods.

---

## 3. Core Domain Hierarchy & Business Entities

The platform enforces strict logical boundaries across 7 primary domain entities:

1. **Organization (`organizations`)**:
   - Represents the registered legal business entity (e.g. *Maple Halal Grocers Inc.*).
   - Holds business registration numbers, tax identifiers, owner contact info, registered office addresses, and verified KYC compliance documents (`organization_documents`).
   - Maintains **Brand Default Tags (`tags`)**, inherited automatically by all branch stores.

2. **Tenant (`tenants`)**:
   - Logical partition key for strict database row isolation.
   - Maps 1:1 with an approved Organization.
   - Operates under lifecycle states: `PENDING`, `ACTIVE`, `SUSPENDED`, `TERMINATED`.

3. **Store Location (`store_locations`)**:
   - Physical supermarket branches, neighborhood bodegas, or dark stores.
   - Configurable per branch: GPS coordinates (latitude/longitude), physical street address, phone number, operating hours JSON, location-specific specialty tags, and custom search keywords.
   - Fulfillment toggles: `is_pickup_available` and `is_delivery_available`.
   - Capability toggles: `has_inventory_module` (stock management) and `has_transaction_module` (checkout vs catalog mode).

4. **Product Master & SKU Variants (`products`, `product_variants`)**:
   - Master Product defines title, description, category, brand, and primary imagery.
   - Product Options & Values model dimensions (Size, Weight, Pack Count).
   - Product Variants represent sellable SKUs with unique barcodes, SKU codes, pricing, compare-at pricing, and variant photos.

5. **Location Inventory & Audit Ledger (`location_inventory`, `inventory_logs`)**:
   - Tracks stock count and safety buffer stock per SKU variant per physical branch.
   - Every stock adjustment (`RESTOCK`, `SALE`, `DAMAGE`, `RETURN`, `ORDER_MODIFIED_RESTOCK`) is immutably logged in `inventory_logs` with actor attribution.

6. **Orders & Fulfillment (`orders`, `order_items`)**:
   - Represents grocery pickup or delivery orders.
   - Progression: `PLACED` -> `CONFIRMED` -> `PREPARING` -> `READY_FOR_PICKUP` / `OUT_FOR_DELIVERY` -> `COMPLETED`.
   - In-store pickers can modify quantities or remove out-of-stock items, which automatically prompts the customer for 1-click approval or rejection.

7. **Store Offers & Deals (`store_offers`)**:
   - Merchants publish promotional deals per store or chain-wide (`PERCENTAGE_DISCOUNT`, `BUY_X_GET_Y`, `SPECIAL_PRICE`).
   - Time-bound auto-expiry and instant real-time disable kill-switch.
   - Nearby shoppers discover deals sorted by real-world geodesic distance ($km$).

---

## 4. Technical Architecture, Security & Performance

- **Backend API**: Java 21 LTS, Spring Boot 3.3.4, Spring Data JPA / Hibernate 6, Spring Security 6, Jakarta Mail.
- **Frontend SPA**: Angular 18+ (Standalone Components, Signals, RxJS), TailwindCSS / Vanilla CSS Glassmorphic System, Lucide Icons.
- **Database**: PostgreSQL 16 on Supabase with UUID extension, JSONB operating hours, and append-only audit ledgers.
- **Hosting & Edge**: Firebase Hosting CDN edge (< 100ms globally) reverse-proxying `/api/**` to containerized Google Cloud Run.
- **Zero-Trust Multi-Tenancy**: Tenant context is embedded in cryptographically signed HMAC-SHA256 JWT claims. Dynamic Hibernate session filters enforce tenant boundary checks at the database layer. No unverified HTTP headers (`X-Tenant-ID`) are trusted.
- **Token Bucket Rate Limiting**: Multi-tier defense across `AUTH` (10 req/min), `CHECKOUT` (15 req/min), `UPLOAD` (10 req/min), `PUBLIC_DISCOVERY` (90 req/min), `CUSTOMER` (120 req/min), `SELLER` (240 req/min), `ADMIN` (360 req/min). Internal rate limit headers are omitted to prevent reconnaissance attacks.
- **3-Tier Synchronized Discovery Caching**: Backend Caffeine cache (60m TTL) + Angular in-memory Map + sessionStorage fallback. Delivers 0ms client-side filtering across tags, keywords, and cities.
- **Product Media Pipeline**: Automated multi-resolution compression transcoding raw uploads into WebP variants (`thumb_` 150px, `card_` 400px, `detail_` 1200px, `orig_` 1920px) with 1-year immutable caching (`max-age=31536000, immutable`).

---

## 5. Pricing & Commercial Structure

| Plan Tier | Price | Target Audience | Key Inclusions |
| :--- | :--- | :--- | :--- |
| **Neighborhood Shopper** | **$0.00** (Free Forever) | Consumers & Families | Cross-store search, in-store prices, Click & Collect pickup, local delivery, deal saving, order tracking. |
| **Retail Store (Monthly)** | **$49 CAD** / store / month | Independent Grocers & Supermarkets | 14-day free trial, digital catalog, real-time inventory ledger, barcode scanning, live fulfillment queue, CSV ingestion, deals engine, 0% commission. |
| **Retail Store (Annual)** | **$470 CAD** / store / year | Independent Grocers & Multi-Store Chains | Includes all monthly features with a 20% annual discount ($39.17 CAD/month effective). |
| **Multi-Store Expansion** | Coterminous proration | Growing Retail Chains | Add up to 5 branch locations with unified billing and synchronized renewal dates. |
| **Wholesalers & Distributors** | Custom B2B partnership | Regional Food Importers | Direct catalog distribution to verified independent supermarkets across Canada. |

---

## 6. Official Knowledge Base & Frequently Asked Questions (FAQs)

### Q1: How do I find grocery stores and specialty markets near me?
**Answer**: You can browse stores on the Cormersi Discover Stores page (`/customer/discovery`) by entering your city, neighborhood, or postal code. You can also filter by cultural specialties (South Asian, East Asian, Middle Eastern, Halal, African pantry, Latin, Organic) or fulfillment options (Click & Collect vs. Local Delivery).

### Q2: Are product prices on Cormersi more expensive than shopping in the physical store?
**Answer**: No. Unlike delivery aggregators that enforce steep markups or price inflations, Cormersi is built on direct merchant transparency. Store owners set their genuine in-store prices, and platform fees are structured to keep everyday grocery shopping affordable for Canadian families.

### Q3: How do Click & Collect (In-Store Pickup) orders work?
**Answer**: When you place an order for in-store pickup, store associates receive your order queue immediately, hand-select your items, and stage them for pickup. You will receive an SMS and email notification when your order is marked Ready for Pickup with curbside or counter collection instructions.

### Q4: Can I order from multiple cultural and specialty grocers?
**Answer**: Yes. Cormersi unites diverse independent grocers across Canada into one network. You can browse authentic spices from an Indian grocer, fresh tortillas from a Latin market, and fresh produce from a local green grocer across individual store catalogs.

### Q5: How does my grocery store or supermarket join Cormersi?
**Answer**: Registering takes under 5 minutes at `/auth/register-seller`. Enter your business details, upload standard business verification documents for KYC verification, and the assisted onboarding team will help verify your account and activate your digital storefront. All accounts start with a 14-day free trial.

### Q6: Can I use Cormersi as a Digital Catalog without enabling online payments?
**Answer**: Absolutely. Cormersi includes a flexible Module Switchboard. You can operate in "Showcase Catalog Mode" (`has_transaction_module = false`) where local shoppers can discover your store, browse your product catalog, and view pricing, while completing purchases in person at your physical checkout counter.

### Q7: How do I import hundreds or thousands of products into my store catalog?
**Answer**: You can upload your entire product catalog in seconds using our Bulk CSV/Excel importer. Cormersi supports multi-variant SKUs (sizes, pack weights, colors), barcodes, photos, category tagging, and automatic location inventory mapping with downloadable diagnostic error workbooks.

### Q8: How does Cormersi differ from big delivery apps like UberEats or DoorDash?
**Answer**: Aggregators charge up to 30% commission, hide customer contact info, and control your brand. Cormersi is merchant-first infrastructure: we charge a transparent, flat subscription ($49 CAD/month), allow direct customer relationships, support multi-location inventory ledgers, and give you 100% data ownership.

### Q9: How do I track the status of my order in real-time?
**Answer**: You can view real-time progression from your Customer Orders page (`/customer/orders`). Order statuses update live from Placed -> Confirmed -> Preparing in Store -> Ready for Pickup / Out for Delivery -> Completed.

### Q10: What happens if a product is out of stock at the store?
**Answer**: Store pickers manage live stock balances through the Cormersi stock ledger. If an item becomes unavailable, associates can adjust quantities or remove items with an explanatory note. The customer receives an instant notification to approve or reject the modification with 1 click.

### Q11: Is my payment and personal information secure on Cormersi?
**Answer**: Yes. Cormersi adheres strictly to Canadian PIPEDA privacy regulations and industry-standard TLS encryption. Customer data is never sold to third-party advertisers, and all payment transactions are tokenized through PCI-DSS certified processors.

### Q12: How are merchants verified before they are listed on the platform?
**Answer**: Every business undergoes strict Know-Your-Customer (KYC) compliance. Platform administrators review official legal documentation, business registration numbers, food safety permits, and physical addresses before granting active marketplace status.

---

## 7. Contact & Official Inquiries

- **General Inquiries & Support**: support@cormersi.com
- **Merchant Onboarding Assistance**: onboarding@cormersi.com
- **Wholesale & Distributor Intake**: wholesale@cormersi.com
- **Headquarters**: Toronto, Ontario, Canada
- **Platform Web URL**: https://cormersi.com