Mivama Core control plane
DocTypes and ownership
Mivama Core is the control plane inside Frappe/ERPNext. It combines standard accounting/customer records with Mivama-specific commercial, hosting, migration, Studio, legal and notification records.
Principal records
| Domain | DocTypes or standard records | Owns |
|---|---|---|
| Identity | User, Contact, Customer | Login identity, language and customer membership |
| Commerce | Subscription Plan, Mivama Stripe Subscription, Mivama Stripe Invoice, Mivama Stripe Event | Plan mapping and external billing mirrors |
| Accounting | Sales Invoice, Payment Entry | Finalized local books for Stripe invoices/payments |
| Hosting | Mivama Hosting Service, desired state and provisioning job records | Requested/actual lifecycle |
| Migration | Mivama Hosting Migration and its events/commands | Transfer authorization and phase |
| Studio | launch/session records and service reports | Eligibility and session authority |
| Legal | legal document, package and acceptance records | Published text and exact accepted versions |
| Customer work | HD Ticket, Project, Task, Mivama Service Request, File | Support and delivery |
| Communication | Portal notifications, email preferences/templates | Customer-facing events |
API organization
mivama_core/api/portal.py is the stable import surface. Domain implementation lives in _portal_accounts, _portal_billing, _portal_stripe, _portal_hosting, _portal_migrations, _portal_studio, _portal_notifications, _portal_preferences, _portal_email_preferences and _portal_workspace.
Methods are whitelisted only where needed. Portal-facing methods identify the current customer and authorize every resource. Runner/Studio internal methods validate a dedicated header secret before exposing a job or target.
Document hooks
hooks.py connects important writes:
- User validate prepares Portal customer settings.
- User after_insert schedules the Mivama Portal welcome email.
- Mivama Stripe Subscription insert/update reconciles hosting lifecycle.
- Service Request, Project, Comment, Communication and HD Ticket changes create localized notifications.
- Sales Invoice submit sends invoice notification.
Hooks should schedule expensive external work rather than block database transactions.
Desk workspace
The Mivama Core Desk workspace is the operator overview. It should expose the operational DocTypes, legal document registry, mail templates/previews, hosting services, jobs, migrations, Stripe mirrors and exception queues. It is not a customer interface.
Schema changes
Frappe DocType JSON and patches are committed with the app. New fields that need data migration get an idempotent patch listed in patches.txt. Deployment runs bench migrate before relying on the field. A missing DocType error means the app schema was not migrated on that site, not that Portal should hide the exception.
Never edit production tables manually to imitate a patch. Keep naming, links, indexes, permissions and backfill together in source control.