Architectural Overview

Vetty is a multi-tenant SaaS that splits cleanly into five cooperating parts:

1. Laravel API + Filament admin (backend/) — the source of truth. Exposes a versioned REST API at /api/v1 and a Filament admin panel at /systemadmin.
2. React SPA (ui/) — the clinic-facing web console; also the web entry-point for pet owners (login, self-registration, a thin portal view and the /reset-password gate).
3. Pet-owner app (vetyy/) — a Flutter consumer app. Pet owners manage their pets, log vaccinations, generate QR share codes to hand records off to a vet, and browse nearby providers (vets, groomers, breeders, trainers).
4. Vet/clinic app (vetdoctor/) — a Flutter clinician app. Vets sign in against their clinic's tenant, see today's schedule and scan an owner's QR to adopt that pet's chart into the clinic.
5. Relational database (MySQL in production, SQLite for local tests) — stores tenants, users, RBAC, audit log, clients, pets, visits with SOAP narratives, prescriptions, lab results, attachments, vaccinations, pet documents, health journal, pet shares, caregivers, appointments, invoices, payments (incl. Razorpay), reminders, templates, opt-outs, service settings, inventory (medicines, stock movements, suppliers, purchase orders), and order requests (commerce).

The platform is designed so one deployment serves many independent veterinary clinics (tenants). Every row in every business table carries a tenant_id; every authenticated request resolves a tenant context through route middleware before reading or writing data. The mobile apps are thin REST clients against the same /api/v1 surface. A handful of public surfaces (marketplace, lost-pet collar tag, share-code redeem, payment webhooks) deliberately operate outside tenant scope — see Multi-tenancy for the rules.

At a glance

Concern	Choice
Backend framework	Laravel 12, PHP 8.2
Admin panel	Filament 5.5
API auth	Laravel Sanctum (token) + session (Filament)
API docs	Zircote Swagger-PHP 6.1 (OpenAPI 3)
Frontend framework	React 18 (Create React App / react-scripts 5)
Styling	Tailwind CSS 3.4, emerald/primary palette
HTTP client	Native fetch wrapper
Routing (UI)	In-app state (module switcher)
State management	React Context (AuthContext, TenantContext)
Database	MySQL (prod), SQLite (tests)
API versioning	URI path (/api/v1)

Headline architecture

Five themes run through the codebase and are expanded in later pages:

• Tenant isolation by convention — every model except User, SystemAdmin, and a handful of cross-tenant resources (caregiver invites, public pet shares, platform-default templates) has a mandatory tenant_id. The ResolveTenantMembership middleware resolves the URL {tenant} placeholder on each request (membership re-check on the audit roadmap).
• Permission-keyed RBAC — App\Auth\PermissionRegistry enumerates ~40 capability keys (e.g. appointment.create, invoice.convert, payment.refund). Roles bundle keys; require.permission middleware blocks fast 4xx; controllers double-check via enforcePermission for row-level decisions; Auditable trait writes every change.
• Thin controllers, rich Form Requests / Resources — validation lives in Http/Requests/Api/V1, output shape lives in Http/Resources/Api/V1, controllers orchestrate.
• Notification driver abstraction — every outbound message goes through one contract (NotificationDriver) and one set of jobs (SendReminderJob, SendReceiptEmailJob, SendCaregiverInviteEmailJob, SendOrderRequestEmailJob). Drivers are switchable per tenant via service_settings. SMS + push are scaffolded but unimplemented.
• Pluggable service layer on the frontend — every remote call goes through a service created by createApiServices(), which can be swapped for a mock implementation via REACT_APP_API_MODE.

Where to go next

• System context — the actors, external systems, and how Vetty fits into a clinic's tech stack.
• High-level architecture — component boundaries and data flow.
• Multi-tenancy — the single-database shared-schema model used here.
• Integration patterns — how the SPA talks to the API, token handling, CORS.
• Security architecture — guards, middleware, token storage.
• Deployment architecture — runtime layout, environments, scaling.