Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/docs/app-packages.md
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
app-packages.md · 9.9 KB · 154 lines

The App Suite — Applications as Installable Packages

DBBASIC ships a suite of everyday applications. None of them required server code: each app is a package of schema + permission rules + (optionally) one page object. The server provides the primitives — records, permissions, search, sharing, files, AI — and apps are data that composes them.

flowchart LR
    P["Package"] --> S["Schema<br/>fields, forms, views,<br/>search, transitions"]
    P --> R["Permission rules<br/>owner rows, public flags,<br/>project sharing"]
    P --> O["Page object<br/>(optional; talks to the<br/>records API as the visitor)"]
    S --> C["Collection records"]
    R --> C
    O --> C
    C --> API["Records API"]
    C --> MCP["MCP tools"]
    C --> SRCH["Global search"]
    C --> AI["AI chat tools"]
    C --> UI["Generated forms/lists<br/>(Scroll)"]

Because every surface reads the same schema and passes the same permission engine, installing an app instantly gives it: a validated records API, generated forms and lists in Scroll, global search, MCP tools for agents, AI chat access, and a live web page — with row-level visibility rules applied identically everywhere.

Each app's page is also realtime: it subscribes to its collection over the shared /ws websocket and re-renders when a record it can see changes, so a note added in one tab (or by an agent) appears in another with no reload — one line per page, permission-filtered like everything else. See design-system and the realtime contract.

The Suite

Fifty-two packages. They are grouped here by what they are FOR rather than alphabetically, because the grouping is the argument: the money apps share one ledger and one composer, the commerce apps share one catalogue and one stock log, and nothing in either column needed server code to exist.

The original slice — records, sharing, capture

PackageCollectionsPageNotable
app-projectsprojects, project_access/projectsThe hub other apps relate to; self-serve sharing grants
app-notesnotes/notesPublic/private per note; permalinks; quick capture
app-taskstasks/tasksStatus lifecycle enforced by a transitions map; assignee access
app-contactscontacts, organizations, interactions, tags/contactsCRM; interactions use the feed list mode
app-articlesarticles/articlesPublish flips one boolean; anonymous-readable blog
app-linkslinks/linksBookmarks with tags
app-eventsevents/calendarCalendar; purpose enum; project sharing
app-filesfiles/filesUploads with quotas; downloads governed by the metadata record
app-templatestemplates/templatesReusable bodies; the thing app-runner executes
app-timerstime_logs, rate_cards/time-logsTime tracking against tasks, and what an hour costs
app-forumforum_categories, forum_topics, forum_replies/forumThreaded discussion on the same permission engine
app-workerprofiles, follows, profile_comments/profile/editPublic profiles and a follow graph

Money — one ledger, one composer, one set of books

PackageCollectionsPageNotable
app-financedenominations, rates, fin_accounts, fin_journals, fin_journal_lines, fin_recurring, fin_closed_periods, expenses/accounts, /journals, /trial-balance, /statements, /expensesDouble-entry: every other money app composes journals through one idempotent composer, provenance-stamped
app-invoicesinvoices, invoice_lines/invoicesLine discounts and tax through the shared object_lines arithmetic
app-paymentspayments, refunds/paymentsCash/accrual basis is configuration; bounces reverse rather than delete
app-billingwallets, wallet_entries, billing_plans, subscriptions, usage_events, usage_summaries/customer-fundsPrepaid balances as a LIABILITY: a top-up is not revenue until the work is done, and the reconciliation proves it
app-bankingvalue_accounts, value_account_counts, bank_import_profiles, bank_statement_imports, bank_lines/reconcileStatement import and matching — the anti-fraud keystone
app-entitiesentities/entitiesMulti-entity: separate books under one login
app-promotionspromotions, promotion_redemptions/promotionsBasket-level codes, rounded once, with every blocker returned at once
app-disputesdisputes/disputesChargebacks and what was said about them
app-integrityanchors/ledger-integrityA daily digest per money ledger, so a break can be bracketed to a day
app-notarynotarizations/notaryStore a digest, check it later — no custody of the document

Commerce — one catalogue, one stock ledger

PackageCollectionsPageNotable
app-catalogproducts, locations, stock_moves, backorders, reorder_suggestions/products, /stock, /locations, /reorder, /backordersStock levels are never stored, only folded from an immutable move log; a variant is a product
app-ordersorders, order_lines/ordersLine discounts, modifiers and tax through object_lines
app-shopcarts, cart_items/shopStorefront and checkout: stock, price and slot are all re-checked at commit
app-shippingshipments, shipment_lines/shipments, /pick-listPartial fulfilment is ordinary business
app-receivingreceipts, receipt_lines—Goods in, at invoice cost, feeding valuation
app-returnsreturn_authorizations/returnsThe reverse trip, authorized before it arrives
app-pickuppickup_slots/pickupCollection windows generated before dawn, so the picker is never empty
app-kitchen—/kitchenThe make-line view of open orders

AI, agents and jobs

PackageCollectionsPageNotable
app-runnertemplate_runs/runsThe job engine: hold money at submission, execute or submit-and-poll, settle once. A run a provider still holds is never abandoned
app-agentsagent_registry/agentsWho is operating this server, and whether it and its own scheduled work are still answering
app-shellshell_preferences, shell_commands, ai_usage/shell, /talkTalk to everything; drop a file in and the model can read it
app-intakescans/scansA photographed receipt becomes a SUGGESTION, never a posting
app-documentssent_documents/documentsOne renderer for every business document

Platform surfaces — the uniform layers

PackageCollectionsPageNotable
app-theme—/appearanceThe generative renderer: list, detail and form from any schema
app-viewsviews/flow, /urlsPages as records — a dashboard is data, not code
app-navnav_entries, attention_sources, attention_counts/The home page and every app's "needs a human" count
app-settingsuser_prefs, feature_flags, ai_prices, app_settings, unit_prices—Server config, per-user prefs, and the price tables
app-sharerecord_shares—Per-record grants that can only ever narrow
app-notifynotify_rules—Declarative event → notification
app-rolluprollup_definitions—Derived aggregates, defined as data
app-materializematerialize_definitions—Scheduled generation of records from a definition
app-threadthread_comments—The comments capability, for any collection
app-collabtask_comments, feed_posts, notifications—Comments, the human+agent coordination feed, notifications
app-feed—/feedThe composed activity stream
app-activity—/activityThe change log, rendered
app-dashboard—/dashboardCounts and queues at a glance
app-messagingmessage_threads, messages, message_recipients, message_drafts/inboxInternal mail on the same permission engine
app-emailemail_outbox—Outbound mail as records, sent by a pass
app-analyticspage_views, conversions/analytics, /visitorsVisitors, bots and us, counted apart
app-privacy—/privacyWhat is collected and why, as a page

Packages without a page are managed entirely through generated UIs, the shell, and MCP — proof that the schema contract carries a whole app's interface.

The Pattern

Every app repeats the same shape. To build a new one, copy app-notes and follow package authoring:

  1. Schema — fields with semantics (docs/schema-forms.md):

types, enums, relations, validation, search.fields, views.list_mode, and transitions for lifecycle fields.

  1. Rules — the standard grants, composed per record:
  • owner rows: {"row_filter": {"owner_id": "$user_id"}}
  • public rows: {"principal": "public", "row_filter": {"is_public": "true"}}
  • project sharing: {"row_filter": {"project_id": "$accessible_projects"}}
  • a public execute grant for the page object, which renders a
 sign-in prompt to anonymous visitors
  1. Page object — one Python file returning HTML; its JavaScript

talks to /collections/{name}/records and /api/search with the visitor's session cookie, so the page holds no data access of its own.

Visibility rules compose per record: a note can be readable because you own it, because it is public, or because it sits in a project shared with you — three rules, no visibility code in the app.

Relations Between Apps

Apps point at each other with validated relation fields, not an association framework: tasks and notes relate to projects, interactions to contacts, time logs to tasks, comments to tasks. A relation is a pointer plus a display hint; writes validate that the target record exists, and nothing joins, cascades, or lazy-loads.