​

Project Status

TattooAPI is currently in the internal-runtime and operator-proof phase. The ontology is broad enough to guide the product, but the public surface should stay narrow until runtime authority and operator workflows are proven.

​

Current Wave Posture

​

Runtime Truth

The target runtime is self-hosted Convex. The current local checkpoint is green on convex_self_hosted, with Wave D runtime, Wave E operator, Kinetic Engine, API build, and Wave D guardrail checks passing. The active cutover goal is simple:

• Convex is the normal read and mutation authority for internal runtime execution.
• File-backed runtime state is limited to bootstrap, degraded fallback, fixture, and maintenance compatibility use.
• Supabase-backed routes are legacy unless explicitly cut over to the runtime adapter or internal Convex admin surface.
• Internal SDK roots should expose operator-safe reads and mutations by default, with maintenance and reseed helpers kept behind explicit compatibility entrypoints.
• Some D3 routes are method-boundary cutovers: GET reads may be runtime-backed while POST, PUT, PATCH, or DELETE remain explicitly blocked or legacy-only until a governed internal Convex mutation contract exists.

​

Auth And Access

WorkOS is the default authentication authority for authenticated and internal-beta access.

• Human/team access uses WorkOS/AuthKit bearer tokens.
• Machine and agent access uses WorkOS API Keys through X-API-Key.
• Convex maps verified WorkOS identities to TattooAPI actors, roles, studio scopes, and artist scopes.
• Valid WorkOS credentials without an active TattooAPI actor mapping return 403.
• Local TattooAPI API key management is retired in WorkOS mode and returns 410.
• Public writes remain blocked.

​

Public Boundary

The public API and docs should stay conservative while Waves D and E close.

• No public write expansion.
• No public ranking formula API.
• No public proof, legal, or compliance mutation path.
• No public SDK launch until read envelopes and operator governance are proven.
• Public discovery docs should describe only supported current behavior.
• Kinetic Engine descriptors can describe internal actionability, blocked states, and governed route paths, but they do not expose public execution.

​

Access Model

TattooAPI should be read as a projection-based platform, not a flat public/private API.

• Public projections are redacted, publish-state-aware, and rights-cleared.
• Future owner-scoped writes belong on explicit authenticated owner route families, not broad public writes.
• Participant-scoped data such as bookings, sessions, quotes, and transaction posture should not become broad public read data.
• Operator projections remain internal for trust, proof, compliance, ranking, legal, and canonical workflow authority.
• Another studio should not see another studio’s draft or unpublished portfolio assets, raw model observations, private pricing data, or client/session records.

​

Cross-Wave Programs

Several programs now span the waves without creating new ontology noun families:

• Marketplace trust, ranking, transaction-readiness, and portfolio proof.
• Pricing and financial-infrastructure depth on existing quote, payment, payout, financing, and market-economics nouns.
• Portfolio Hydration V1 for Sanity CMS, CRM exports, GPT Vision metadata observations, and Firecrawl or Perplexity evidence, all staging-only until operator approval.
• Future SDK, website, free-tool, tattoo.co integration, guest-spot marketplace, governed delist intake, and Ghostline or Tattoo Sketch ideas.

These are real product directions, but they remain gated by runtime authority, operator review, rights, consent, provenance, and human decision lineage.

​

Wave F+ Gate Summary

Wave F+ work should proceed as readiness and preview until activation gates are met.

• Wave F: public read envelopes, SDK/tool contracts, public page candidates, and free-tool concepts stay read-only and preview-only.
• Wave G: governed datasets require review lineage, rights posture, consent posture, and auditability before harvest.
• Wave H: intelligence tasks can be specified and evaluated, but no model training starts without governance-cleared data.

The next practical gate is a public-read preview layer for already-reviewed Studio, ArtistProfile, PortfolioAsset, and Design data, not broad public mutation or unreviewed scraping. See Future Wave Gates.

​

What To Build Against Today

Use the current public read surface and treat it as transitional:

• Quickstart
• Search
• Studios
• API Reference

​

Usable This Week

Public no-auth reads (promoted):

• GET /health
• GET /studios

Public compatibility ingress that is not the promoted product surface:

• runtime docs metadata
• legacy auth compatibility routes
• Stripe webhook ingress
• search autocomplete helper

Authenticated discovery beta:

• GET /search

Authenticated creative read beta:

• GET /artists
• GET /artists/[id]
• GET /portfolios
• GET /portfolios/[id]
• GET /designs
• GET /designs/[id]

Owner-scoped creative read beta:

• GET /me/portfolio-assets
• GET /me/portfolio-assets/[id]
• GET /me/designs
• GET /me/designs/[id]

Public write methods remain blocked or legacy-boundary until governed Convex write contracts are promoted. Owner write methods exist only as gated contract responses today.

​

Hydration Status

The next data priority is governed first-party hydration, not broad scraping.

• Google Workspace row extraction is staged with 71,080 rows.
• Google directory hydration is verified with 63,209 promotable rows.
• The current sync reports expect 28,894 canonical studio profiles and 3,996 canonical artist profiles with source lineage.
• Creative canary promotion has 5 selected candidates in canonical PortfolioAsset and Design records.
• External law/compliance canaries now flow through the Ontology Guidance MCP and source-pack staging as review-ready artifacts only.
• Current law sync packs include HI/NV and CA/TX/NY/FL/WA citation-backed canaries plus Git-like diff reports for same-cohort refreshes.
• Sanity managed-studio connections are scaffolded for selected tattoo.agency-managed studios, but extraction remains blocked until real project IDs, datasets, and local token env aliases are configured.
• Sanity tokens are not stored in git, docs, reports, API responses, Mastra, or Convex.

Law/compliance remains staging and review only. No public legal advice surface or Convex canonical law sync is active from scraped records until an approval-gated promotion path lands.

​

Internal Agent Runtime

Mastra is now adopted as the internal supervised-agent runtime for Wave E work.

• Convex plus the internal SDKs remain canonical runtime authority
• Mastra uses a mixed-maturity agent registry: five fully wired agents and the rest scaffolded but visible in Studio
• Runtime mutation tools are approval-gated and default to dry-run
• Local Studio and Swagger endpoints are internal development infrastructure, not public API products.

For deeper product context, use:

• Trust Model
• Ontology Reference
• Open Source Build