This is the target-state model of Tiny Solutions for developers: a multi-agency
Early Intervention operating system for service coordination, evaluation,
provider work, billing, payroll, reporting, and compliance.

This page is intentionally comprehensive. It can mention implementation
maturity, code-area boundaries, and source files. It still must not include
secrets, credentials, real child data, production environment values, or anything
that would weaken HIPAA controls.

## Product in one picture [#product-in-one-picture]

Tiny Solutions is one complete application. Every agency receives every work
area. Server-enforced role, relationship, and minimum-necessary access decide
what a person may read or change; configurable feature switches do not.

<Mermaid
  chart="flowchart TB
  Agency[&#x22;EI agency scope&#x22;] --> Core[&#x22;Core platform<br/>agency, members, auth, audit, children, files, billing account&#x22;]
  Core --> SC[&#x22;Service coordination<br/>referrals, child record, notes, documents, transition, discharge&#x22;]
  Core --> Eval[&#x22;Evaluations<br/>MDE scheduling, evaluators, forms, outcomes&#x22;]
  Core --> Services[&#x22;Provider services<br/>providers, authorizations, service delivery, session notes&#x22;]
  Core --> Claims[&#x22;Claims billing<br/>authorizations, claims, remittance, denials&#x22;]
  Core --> Payroll[&#x22;Payroll<br/>pay rates, payable activity, exports&#x22;]
  Core --> Reports[&#x22;Reports<br/>compliance, operations, finance, audit packets&#x22;]

  SC --> Today[&#x22;Role-aware work<br/>personal and agency queues&#x22;]
  Eval --> Today
  Services --> Today
  Claims --> Reports
  Payroll --> Reports"
/>

## Current implementation [#current-implementation]

The product is in active development with synthetic data only. The target model
is implemented directly; there is no compatibility layer for earlier schemas or
earlier agency configurations. A service agency stores only the authorization facts it
needs to deliver, document, staff, and bill its own services for a child.

| Area                                   | Status                           | Current route or code surface                                                                                       |
| -------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Marketing and public docs              | Shipped                          | `src/app/(marketing)`, `src/app/docs`, `content/docs`                                                               |
| Auth and account recovery              | Shipped                          | `src/app/(auth)`, `convex/auth.ts`, `convex/authOrchestrator.ts`, `convex/authRecovery.ts`                          |
| Agency provisioning                    | Shipped                          | `convex/lib/tenantProvisioning.ts`, `convex/agencyConfigs.ts`                                                       |
| Home                                   | Shipped as onboarding-only       | `src/app/(dashboard)/home/page.tsx`                                                                                 |
| Children list                          | Shipped                          | `src/app/(dashboard)/children/page.tsx`, `convex/children.ts`                                                       |
| Child record                           | Shipped                          | `src/app/(dashboard)/children/[childId]`, child tabs for basic info, medical, insurance, documents, notes, activity |
| New child                              | Shipped core flow                | `src/app/(dashboard)/children/new/page.tsx`, `convex/children.ts`, `convex/drafts.ts`                               |
| Medical info                           | Shipped                          | `convex/medicalInfo.ts`, child Medical Info tab                                                                     |
| Insurance                              | Shipped                          | `convex/insurance.ts`, `convex/childInsurancePolicies.ts`, child Insurance tab                                      |
| Documents and notes                    | Shipped                          | `convex/documents.ts`, `convex/notes.ts`, child Documents and Notes tabs                                            |
| Case activity timeline                 | Shipped                          | child record activity surface backed by audit and domain events                                                     |
| Member roster                          | Shipped                          | `src/app/(dashboard)/members/page.tsx`, `convex/members.ts`. Settings Members is a next.config door to `/members`.  |
| Settings                               | Shipped                          | agency, billing, security, sessions, SSO, recovery, audit, document types                                           |
| Subscription billing                   | Shipped                          | `convex/billing.ts`, `convex/billingActions.ts`, Stripe                                                             |
| Audit log                              | Shipped                          | `convex/audit.ts`, `convex/lib/withAudit.ts`                                                                        |
| Agency service delivery                | Active development               | `convex/serviceDelivery.ts`, `convex/schema/serviceDelivery.ts`                                                     |
| Assignment and coordinator designation | Active development               | `convex/assignment.ts`, `convex/schema/children.ts`                                                                 |
| Schedule, payroll, reports             | Available and active development | `/schedule`, `/payroll`, `/reports`                                                                                 |

## Architecture model [#architecture-model]

The app is a full-stack reactive monolith. Next.js owns routes and UI. Convex is
the database, server function layer, storage layer, scheduler, and HTTP endpoint
host. Better Auth stores identity data in Convex through its adapter. Stripe and
Resend are external services with narrow boundaries.

<Mermaid
  chart="flowchart TB
  User[&#x22;Agency user<br/>Owner, Admin, Member, read-all Member&#x22;] --> Browser[&#x22;Browser&#x22;]

  subgraph Next[&#x22;Next.js app on Vercel&#x22;]
    Marketing[&#x22;Marketing routes&#x22;]
    Docs[&#x22;Fumadocs docs site<br/>content/docs&#x22;]
    AuthUI[&#x22;Auth routes<br/>login, signup, invite, recover, verify&#x22;]
    Dashboard[&#x22;Dashboard routes<br/>children, members, settings&#x22;]
    Proxy[&#x22;proxy.ts<br/>optimistic route protection&#x22;]
    ConvexClient[&#x22;Convex React hooks<br/>useQuery, useMutation&#x22;]
  end

  subgraph Convex[&#x22;Convex backend&#x22;]
    Http[&#x22;HTTP routes<br/>Better Auth, Stripe webhooks&#x22;]
    AgencyGate[&#x22;Agency scope gate<br/>scoped query, mutation, and action wrappers&#x22;]
    Domain[&#x22;Domain functions<br/>children, members, billing, documents, notes&#x22;]
    Storage[&#x22;Convex file storage<br/>agency-scoped PHI files&#x22;]
    Db[&#x22;Convex database<br/>agency-scoped tables&#x22;]
    Audit[&#x22;Append-only audit log&#x22;]
    Crons[&#x22;Crons and scheduled jobs&#x22;]
  end

  subgraph External[&#x22;External systems&#x22;]
    BetterAuth[&#x22;Better Auth adapter&#x22;]
    Stripe[&#x22;Stripe&#x22;]
    Resend[&#x22;Resend<br/>no PHI email&#x22;]
    Google[&#x22;Google OAuth&#x22;]
    Turnstile[&#x22;Cloudflare Turnstile&#x22;]
    EIHub[&#x22;EI Hub / NYEIS<br/>manual boundary&#x22;]
  end

  Browser --> Next
  Dashboard --> ConvexClient
  ConvexClient --> AgencyGate
  AuthUI --> Http
  Http --> BetterAuth
  BetterAuth --> Db
  BetterAuth --> Google
  BetterAuth --> Turnstile
  BetterAuth --> Resend
  Domain --> Db
  Domain --> Storage
  Domain --> Audit
  Billing[&#x22;billing actions&#x22;] --> Stripe
  Stripe --> Http
  Domain --> Resend
  Crons --> Domain
  EIHub -.->|&#x22;manual copy, upload, reconciliation&#x22;| Dashboard"
/>

## Route and surface map [#route-and-surface-map]

<Mermaid
  chart="flowchart TB
  Root[&#x22;/&#x22;] --> Marketing[&#x22;Public marketing<br/>pricing, security, migrate, integrations, changelog&#x22;]
  Root --> Docs[&#x22;/docs<br/>public documentation site&#x22;]
  Root --> Auth[&#x22;Auth<br/>/login /signup /invite /recover /verify&#x22;]
  Auth --> Home[&#x22;/home<br/>onboarding-only once agency exists&#x22;]
  Home --> Children[&#x22;/children<br/>main work surface&#x22;]
  Children --> NewChild[&#x22;/children/new&#x22;]
  Children --> ChildRecord[&#x22;/children/[childId]<br/>Basic, Medical, Insurance, Documents, Notes, Activity&#x22;]
  Home --> Members[&#x22;/members<br/>staff directory&#x22;]
  Home --> Settings[&#x22;/settings&#x22;]
  Settings --> Agency[&#x22;agency&#x22;]
  Settings --> MembersAdmin[&#x22;members&#x22;]
  Settings --> Billing[&#x22;billing&#x22;]
  Settings --> Audit[&#x22;audit&#x22;]
  Settings --> Security[&#x22;security, sessions, SSO, recovery&#x22;]
  Home --> PartialRoutes[&#x22;partial or deferred routes<br/>today, assignments, directory, drafts, payroll, reports&#x22;]"
/>

## Domain class model [#domain-class-model]

This is UML-style, but encoded as a Mermaid flowchart so it renders in the docs
site. Edge labels carry the multiplicities and relationship meaning.

<Mermaid
  chart="flowchart LR
  Agency[&#x22;Agency<br/>agency scope / Better Auth agency record&#x22;]
  Member[&#x22;Member<br/>user in agency&#x22;]
  Role[&#x22;Role<br/>owner, admin, member, guest<br/>plus capabilities&#x22;]
  Subscription[&#x22;Subscription<br/>plan, seats, status&#x22;]
  PlanLimit[&#x22;PlanLimit<br/>child and seat caps&#x22;]
  Child[&#x22;Child<br/>central case record&#x22;]
  Family[&#x22;Family&#x22;]
  Contact[&#x22;Contact<br/>parent, guardian, emergency&#x22;]
  Referral[&#x22;Referral<br/>incoming or linked episode&#x22;]
  Insurance[&#x22;InsurancePolicy<br/>Medicaid, commercial, none&#x22;]
  Consent[&#x22;ConsentRecord&#x22;]
  Document[&#x22;Document<br/>metadata plus storage id&#x22;]
  Note[&#x22;Note&#x22;]
  Medical[&#x22;MedicalInfo<br/>alerts, meds, lead, immunization&#x22;]
  IFSP[&#x22;IFSPPlan&#x22;]
  Authorization[&#x22;Authorization<br/>service line&#x22;]
  Assignment[&#x22;Assignment<br/>person staffed to work&#x22;]
  CoordinatorDesignation[&#x22;Coordinator designation<br/>Initial or Ongoing&#x22;]
  Provider[&#x22;Provider<br/>future directory entity&#x22;]
  Audit[&#x22;AuditLog<br/>append only&#x22;]

  Agency -->|&#x22;1 to many&#x22;| Member
  Member -->|&#x22;has one or more&#x22;| Role
  Agency -->|&#x22;0 or 1 active&#x22;| Subscription
  Subscription -->|&#x22;enforces&#x22;| PlanLimit
  Agency -->|&#x22;1 to many&#x22;| Child
  Child -->|&#x22;belongs to 1&#x22;| Family
  Family -->|&#x22;1 to many&#x22;| Contact
  Child -->|&#x22;0 to many&#x22;| Referral
  Child -->|&#x22;0 to many&#x22;| Insurance
  Child -->|&#x22;0 to many&#x22;| Consent
  Child -->|&#x22;0 to many&#x22;| Document
  Child -->|&#x22;0 to many&#x22;| Note
  Child -->|&#x22;0 to many&#x22;| Medical
  Child -->|&#x22;0 to many&#x22;| IFSP
  IFSP -->|&#x22;1 to many&#x22;| Authorization
  Authorization -->|&#x22;0 to many staffing records&#x22;| Assignment
  Child -->|&#x22;0 to 2 designation slots&#x22;| CoordinatorDesignation
  Agency -->|&#x22;1 to many immutable rows&#x22;| Audit
  Audit -->|&#x22;records actions by&#x22;| Member
  Audit -->|&#x22;records changes to&#x22;| Child"
/>

## Child Stage and Referral [#child-stage-and-referral]

A Child has one Stage. Stage is the Agency's word. Tiny never computes it.
The generated Case stage machine lives in `docs/state-diagrams.md`.

A Referral is a record of what the Agency sent. It has no status of its own
(ADR-0021). The Child exists from the first keystroke of a Referral. If the
Referral comes back, the Agency records the Initial Service Coordinator
authorization. Stage may then move by the Agency mapping. If it does not
come back, the Agency changes Stage. Nothing on the Referral changes.

Tiny does not copy EI Hub's Open or Closed referral status, and it does not
arm the 45-day clock.

## Member and access lifecycle [#member-and-access-lifecycle]

<Mermaid
  chart="stateDiagram-v2
  [*] --> Invited: admin sends invite
  Invited --> Active: invite accepted
  Invited --> Revoked: admin revokes invite
  Invited --> Expired: token expires
  Active --> RoleChanged: admin changes role or capability
  RoleChanged --> Active: access recalculated
  Active --> Removed: owner removes member
  Removed --> Active: reinstated within ninety days
  Active --> LeftAgency: member leaves
  Active --> OwnershipTransferred: owner transfers agency
  OwnershipTransferred --> Active: new owner active
  Revoked --> [*]
  Expired --> [*]
  LeftAgency --> [*]
  Removed --> [*]"
/>

## Document lifecycle [#document-lifecycle]

Documents are file-backed records. The final target keeps the same foundation and
adds a richer inbox and library for agency-wide filing work.

<Mermaid
  chart="stateDiagram-v2
  [*] --> UploadUrl: generate upload URL
  UploadUrl --> StoredFile: browser uploads to Convex storage
  StoredFile --> LinkedDocument: metadata row links file to child or record
  LinkedDocument --> NeedsReview: document enters review queue when required
  NeedsReview --> Verified: admin or authorized staff verifies
  NeedsReview --> Refiled: document type or owner corrected
  Verified --> Retained: retained after case closure
  Refiled --> LinkedDocument
  Retained --> [*]"
/>

## Billing lifecycle [#billing-lifecycle]

<Mermaid
  chart="stateDiagram-v2
  [*] --> Free: agency created without billing state
  Free --> ActiveSubscription: Pro checkout confirmed
  ActiveSubscription --> PastDue: invoice payment fails
  PastDue --> ActiveSubscription: payment recovers
  PastDue --> Free: subscription canceled or expires
  Free --> ActiveSubscription: resubscribe"
/>

## Product dependency map [#product-dependency-map]

All work areas share the same agency, child, member, file, and audit foundations.

<Mermaid
  chart="flowchart TB
  Core[&#x22;Core<br/>Agency, Member, Role, Child, Family, Contact, File, Audit, Subscription&#x22;]
  SC[&#x22;Service coordination<br/>Referral, transition, discharge, notes, documents&#x22;]
  Eval[&#x22;Evaluation<br/>MDE workflow, evaluators, required forms, outcomes&#x22;]
  ProviderWork[&#x22;Provider services<br/>Provider, Credential, capacity, service delivery&#x22;]
  PlanAuth[&#x22;Agency authorizations<br/>service facts, staffing, amendments&#x22;]
  Claims[&#x22;Claims billing<br/>claim assembly, submission, denial work&#x22;]
  Payroll[&#x22;Payroll<br/>pay rates, payable activity, exports&#x22;]
  Reports[&#x22;Reports<br/>audit packets, productivity, compliance, finance&#x22;]
  Directory[&#x22;Directory<br/>contacts, agencies, providers, labels, favorites&#x22;]
  Inbox[&#x22;Document inbox and library<br/>filing, verification, templates&#x22;]

  Core --> SC
  Core --> Eval
  Core --> ProviderWork
  Core --> Directory
  Core --> Inbox
  SC --> PlanAuth
  Eval --> PlanAuth
  ProviderWork --> PlanAuth
  PlanAuth --> Claims
  PlanAuth --> Payroll
  Claims --> Reports
  Payroll --> Reports
  Inbox --> Reports
  SC --> Reports
  Eval --> Reports
  ProviderWork --> Reports"
/>

## Work-area availability [#work-area-availability]

Every work area is part of the product for every agency. Implementation maturity
is not an entitlement boundary and must never hide a destination or produce an
upgrade state.

| Work area                     | Product contract                                                                                    |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| Child and referral operations | Referral intake, child record, notes, documents, transitions, and role-aware work queues.           |
| Evaluations                   | MDE assignment, scheduling, evaluation documents, outcomes, and evaluator workload.                 |
| Agency service delivery       | Service authorization facts, amendments, staffing, visits, notes, and reports for this agency only. |
| Billing                       | Subscription management plus EI claims, remittances, denials, and financial work queues.            |
| Payroll                       | Pay-rate rules, payable activity, exports, and reconciliation.                                      |
| Reports                       | Compliance, operational, billing, payroll, and audit reports.                                       |
| Directory and documents       | Shared professional and agency records, filing, verification, and templates.                        |

## Developer ownership map [#developer-ownership-map]

| Subsystem                               | Primary source                                                                                |
| --------------------------------------- | --------------------------------------------------------------------------------------------- |
| Docs site                               | `content/docs`, `src/app/docs`, `src/components/mdx.tsx`, `source.config.ts`                  |
| Navigation                              | `src/lib/nav-config.ts`, `src/components/shared/AppSidebar.tsx`                               |
| App shell                               | `src/app/(dashboard)/layout.tsx`, shared shell components                                     |
| Auth                                    | `convex/auth.ts`, `convex/betterAuth`, `src/lib/auth.ts`, `src/lib/authKit.ts`                |
| Agency scope                            | `convex/lib/tenantScope.ts`, `convex/lib/permissions.ts`                                      |
| Children                                | `convex/children.ts`, `convex/schema/children.ts`, `src/app/(dashboard)/children`             |
| New child                               | `convex/children.ts`, `convex/drafts.ts`, `/children/new`                                     |
| Insurance                               | `convex/insurance.ts`, `convex/childInsurancePolicies.ts`, `src/components/insurance`         |
| Documents                               | `convex/documents.ts`, `convex/files.ts`, `convex/documentTypes.ts`                           |
| Notes                                   | `convex/notes.ts`, `convex/notesActions.ts`                                                   |
| Medical info                            | `convex/medicalInfo.ts`, child Medical Info components                                        |
| Agency service delivery                 | `convex/serviceDelivery.ts`, `convex/lib/serviceDelivery`, `convex/schema/serviceDelivery.ts` |
| Assignment and coordinator designations | `convex/assignment.ts`, `convex/schema/children.ts`                                           |
| Members and roles                       | `convex/members.ts`, `src/components/members`, members routes                                 |
| Billing                                 | `convex/billing.ts`, `convex/billingActions.ts`, `src/components/billing`                     |
| Audit                                   | `convex/audit.ts`, `convex/lib/withAudit.ts`, settings audit route                            |
| Security settings                       | sessions, trusted devices, SSO, recovery, assurance, break-glass access                       |
| Static guards                           | `scripts/check-*.ts`, `scripts/guards.ts`, `docs/enforcement.md`                              |

## Invariants developers must preserve [#invariants-developers-must-preserve]

1. Public Convex functions use agency-scoped wrappers. Do not expose raw
   unscoped database reads from public functions.
2. Audit logs are append-only. Domain writes log through the established audit
   helpers and never patch, replace, or delete audit rows.
3. Email contains no PHI. Resend messages use opaque links and generic text.
4. Convex is the server state path. Dashboard data uses Convex queries and
   mutations, not ad hoc REST fetches.
5. Role and capability checks happen on the server. Browser navigation filtering
   is only a convenience layer.
6. Files are private storage objects with agency-scoped metadata and signed
   access paths.
7. The product surface is complete for every agency. Role, relationship, and
   record authorization may restrict an action; feature switches may not.
8. Public docs can describe architecture and roadmap, but must never publish
   credentials, secrets, real PHI, or environment-specific private values.

## Implementation maturity [#implementation-maturity]

Implementation maturity is tracked in Linear, not encoded as agency
configuration. An unfinished flow stays an engineering issue against its final
workflow contract; it does not become an enable/disable switch, hidden route,
upgrade prompt, compatibility mode, or alternate data model.

## How to extend this model [#how-to-extend-this-model]

When a new concept lands, update this page in the same change set as the
implementation. Add it to the domain model and developer ownership map. If it
introduces a new lifecycle, add a state diagram. Every agency receives the
complete application; do not introduce agency feature switches.