mono/packages/ui/docs/entities.md

Entity Types

The serving endpoint currently handles multiple distinct entity models within the platform. According to the route registrations in server/src/products/serving/index.ts, these are the primary operational entities managed by the system:

1. Content Entities

• Posts (db-posts.ts): Primary content entities. Used in feeds and can be exported in various formats (PDF, JSON, HTML, Markdown, Rich HTML).
• Pages (pages-crud.ts): Standalone pages within the platform. Supports full version control (PageVersions), email rendering, and multiple export formats.
• Categories (db-categories.ts): Taxonomies for grouping and filtering items. Includes CategoryItems for linking entities to a category.

2. Media & Engagement Entities

• Pictures (db-pictures.ts): Standalone media assets supporting versioning, linking/unlinking, and batch uploads.
• Comments (db-pictures.ts): User engagement texts, typically attached to media or content, with support for toggling likes.

3. Structural Entities

• Types (db-types.ts): Dynamically managed content definitions or data schemas.
• Layouts (db-layouts.ts): View templates and rendering layouts for the front-end or app components.

4. Internationalization (i18n) Entities

• Translations & Widget Translations (db-i18n.ts): Granular text records mapped to UI components.
• Glossaries & Glossary Terms (db-i18n.ts): Translation dictionaries and terminology synchronization mappings (e.g., DeepL integration).

5. User Entities (db-user.ts)

• Profiles: The public-facing identity (profiles table), storing fields like username, display_name, bio, and avatar_url. This entity relies on a centralized in-memory cache for high-performance reading and augmentation across the application.
• User Secrets: Secure configurations (user_secrets table) such as api_keys, variables, shipping_addresses, and vendor_profiles. The API ensures api_keys are dynamically masked (showing only the last 4 characters) when served.
• Admin Users: Management entities that bundle Supabase Auth identities with their respective profiles and settings, allowing backend user lifecycle management.

6. Access Control (ACL) Entities (db-acl.ts)

• ACL Settings: A resource-agnostic wrapper used to define access rules. It delegates to specific backends (IAclBackend, e.g., memory/VFS or Supabase DB) and encapsulates the owner and AclEntry definitions (which specify userId or group, scoped to a path with allowed permissions).
• Global ACL Groups: Hierarchical roles persisted in the database (acl_groups), supporting relationships via parent_id.
• Group Memberships: Maps users to Global Groups (acl_group_members). The ACL engine consolidates these explicit memberships with virtual identities (e.g., anonymous, authenticated, registered, admin) and local resource groups to evaluate effective permissions dynamically.

7. Platform Integration Entities (endpoints/products.ts)

• Products: Platform-level features or logical product definitions (products table). Each product holds an id, name, slug, description, and a flexible settings JSON object (supporting logic like enabled, default_cost_units, and default_rate_limit). Their administrative endpoints support full CRUD operations. Notably, deleting a product automatically removes any associated product-acl records from the resource_acl table.

8. Contacts & Integrations Entities (products/contacts/index.ts)

• Contacts: The primary address book entity (contacts table), storing fields like name, organization, emails, phone, and address. Supports bulk operations and bidirectional data exchange formats (including parsing and serialization for vCard).
• Contact Groups & Memberships: Organizational buckets (contact_groups) and their associated mapping table (contact_group_members) used to categorize constraints.
• Mailboxes (IMAP Integration): Configuration records enabling automated connection to external email servers for contact harvesting. Includes specific OAuth2 handling for Gmail alongside traditional IMAP credential setups.

9. Server Middleware Layers (index.ts & middleware/)

The Polymech server pipeline implements a layered middleware architecture to enforce security, monitoring, and authentication before requests reach the endpoints.

• Content Security & CORS (csp.ts): Sets up strict Content Security Policies, secure HTTP headers, and intercepts OPTIONS preflight requests globally.
• Security & Blocking Pipeline:
  • AutoBan Middleware (autoBan.ts): Applied globally (*). Acts as an intrusion detection system (IDS) that catches directory traversal probes and enforces rate-limit bans across all HTTP traffic.
  • Blocklist Middleware (blocklist.ts): Applied specifically to /api/* to enforce absolute IP or user-based blocklists before API logic is executed.
• Analytics (analytics.ts): Traps requests globally (*) for telemetry, observability, and usage metric tracking.
• Authentication & Authorization (auth.ts):
  • Optional Authentication: By default, checks for a Bearer token or ?token= query parameter (e.g., for SSE) and validates it against Supabase via an aggressive cache. Routes registered in the PublicEndpointRegistry (and the core /api/products route) bypass authentication requirements entirely.
  • Admin Enforcement: Intercepts requests meant for the AdminEndpointRegistry. Requires a valid session payload and queries user_roles to strictly enforce the admin capability.
• Content Compression: Global hono/compress usage that is augmented with custom streaming logic to seamlessly gzip specialized, heavy geometry and vector assets (e.g., model/stl, model/obj, vnd.dxf).

10. Product Tiering / Monetization (Freemium, Pro) via ACL Middleware [Proposed Architecture]

To seamlessly integrate subscription tiers on the server-side without overhauling existing database models, the platform can leverage the new ACL engine and middleware layers:

• ACL Group Hierarchy For Tiers: Instead of building custom licensing tables, product tiers map directly to Global ACL Groups utilizing inheritance.
  • tier:freemium (assigned automatically to registered users).
  • tier:pro (inherits capabilities from freemium).
  • Upon webhook confirmation (e.g., Stripe payment), the user is upserted into the tier:pro group via acl_group_members.
• Product-Level Resource Gating: The resource_acl table links an existing Product (from the products table, e.g., contacts module) to a tier group (tier:pro) with explicit access permissions.
• Server Middleware Gating (productAclMiddleware.ts): A dedicated middleware sits after auth.ts (so userId and user.groups are resolved).
  • Using the IAclBackend, it evaluates if the user's combined implicit/explicit groups trigger an ALLOW for the requested API route. If denied, it handles the 403 Payment/Upgrade Required response universally, keeping endpoint code clean.
• Dynamic Rate Limits: The products.settings JSON (which holds default_rate_limit) can be parsed by middleware. The apiRateLimiter can then dynamically adjust throttles based on the user's tier, heavily restricting Freemium traffic while allowing Pro users unhindered access.

Example Integration Flow: Upgrading a User from Free to Pro

1. Transaction Event: A user completes a checkout, and the external payment processor (e.g., Stripe) fires a secure webhook (like checkout.session.completed) to the backend (POST /api/webhooks/billing).
2. Signature Verification: The server intercepts the webhook payload and validates its cryptographic signature.
3. Identity Resolution: The server maps the external customer_id from the payload back to the core Supabase user_id.
4. ACL Upsertion: The backend inserts or modifies the acl_group_members table, mapping the resolved user_id strictly to the tier:pro global ACL group.
5. Cache Invalidation: The server evicts the user's cached identity and permissions footprint from high-speed memory, forcing a fresh lookup.
6. Instant Authorization: Upon the user's next API call, the request hits the productAclMiddleware. The IAclBackend recalculates the merged groups, detects the active tier:pro inheritance, and structurally allows access to Pro-restricted product features and modified rate limit overrides.

This brief documentation reflects the current state of CRUD routing and API interactions across the architecture.