Skip to main content

Platform Overview

This reference explains how the three core repositories—mito/mito-api, mito/mito-api-docs, and mito/mito-web—work together to deliver the end-to-end Mito experience. Each section calls out the functionality that exists today, the main gaps, and the typical scenarios the stack supports.

Repositories at a Glance​

  • mito/mito-api (Spring Boot, domain-driven design): owns authentication, workspace/project lifecycle, and canvas asset persistence. Key modules live under src/main/java/ai/mito/{application,domain,infrastructure}.
  • mito/mito-api-docs (Swagger UI): publishes the OpenAPI contract in swagger.yml and provides a containerised viewer for developers.
  • mito/mito-web (React + Vite): renders the infinite canvas, project dashboard, and authentication flows. Hooks in src/services wrap the REST API, while components under src/components/*Node render asset types.

End-to-End Functional Areas​

Authentication & Session Lifecycle​

Functionality

  • /auth/signup, /auth/signin, /auth/refresh endpoints (defined in swagger.yml) handle account creation, JWT issuance, and refresh tokens.
  • SignUpUser automatically provisions a “Personal” workspace for new accounts and persists memberships through SqlWorkspaces.
  • TokenAuthenticator + JwtAuthenticationFilter secure downstream project and asset endpoints.
  • mito-web uses AuthContext and guards in src/lib/authGuards.ts to gate routes and to inject bearer tokens into API calls.

Limitations

  • No password reset or email verification workflow.
  • Error messages bubble up as generic runtime exceptions; clients receive limited detail.
  • Refresh tokens live in SQL but lack rotation/audit trails.

Primary use cases

  • Onboarding new creators into a default personal workspace.
  • Continuing authenticated sessions inside the web canvas without repeated login prompts.

Workspace & Project Management​

Functionality

  • GET /workspaces/ returns the authenticated user’s memberships; WorkspaceProvider auto-selects the first workspace and persists the choice in local storage.
  • GET /workspaces/{id} (via SqlProjects.byWorkspaceAndUser) lists accessible projects; ProjectsRoute renders them alongside skeleton loaders.
  • POST /projects/ creates projects tied to a workspace; the React hook useCreateProject triggers navigation to the project canvas.
  • PUT /projects/{id} and DELETE /projects/{id} exist server-side (RenameProject, RemoveProject) with permission checks through ProjectPermissions.

Limitations

  • Workspace creation/invitation beyond the default owner flow is not exposed via API or UI.
  • Front-end still lacks UI handlers for rename/duplicate/delete because the API contract is not fully wired to Swagger or services.
  • Soft-deleted projects remain in the database; there is no restore endpoint.

Primary use cases

  • Organising creative initiatives by workspace (studio vs. client) and project.
  • Quickly spinning up new projects from the dashboard and jumping into the canvas.

Canvas Assets & Creative Surface​

Functionality

  • Assets live in SqlAssets and support image, document, text, and group types, each with coordinates, dimensions, and optional annotations.
  • POST /projects/{id}/assets/ accepts multipart uploads: metadata in the data part and a file placeholder (front-end supplies real files or dummy blobs for text).
  • GET /projects/{id} returns a ProjectAssetsView aggregating project metadata plus all assets; getProjectAssets hydrates React components such as ImageNode, TextNode, DocumentNode, and GroupNode.
  • PUT /projects/assets/{id} updates positioning, content, and annotations; UI bindings exist in node toolbars and drag/resize handlers.
  • GroupAsset allows stacking asset ids for composite layouts, surfaced by StackFocusOverlay on the front end.

Limitations

  • Binary file storage/backing CDN is not yet integrated; backend stores only JSON metadata (e.g., URLs) and ignores the uploaded file stream.
  • Annotation model is a single string; no structured comments or collaboration metadata.
  • No concurrency control—simultaneous edits can overwrite positions/content.

Primary use cases

  • Building moodboards by dropping annotated images/documents on the canvas.
  • Authoring textual briefs directly in canvas text nodes with inline formatting.
  • Grouping assets to maintain storyboard panels or scene beats.

API Contract & Documentation​

Functionality

  • mito-api-docs/swagger.yml captures authentication, workspace, project, and asset endpoints; developers can run docker compose up to review the live spec.
  • Shared schemas (Workspace, Project, Asset, AssetCreate) are the source for client SDK generation and front-end TypeScript models.
  • The spec anchors postman collections and QA verification during backend changes.

Limitations

  • Spec omits newer endpoints (project rename/delete, asset update) and deviates from actual request shapes (e.g., multipart uploads vs. JSON bodies).
  • No automated spec drift detection; manual discipline required after code changes.
  • Scenario or workflow documentation is absent, so consumers must infer sequences from endpoints alone.

Primary use cases

  • Guiding front-end service wrappers when wiring API calls.
  • Sharing the public contract with partners who want to integrate against the backend.

Cross-Cutting Gaps & Risks​

  • Observability: Minimal logging/metrics; failures surface as generic 500s for both clients.
  • Access controls: Role checks rely solely on workspace memberships; there is no project-level collaborator concept yet.
  • Data hygiene: Lack of migrations in the repo indicates schema management happens elsewhere; contributors need clarity before adding tables/columns.
  1. Align the OpenAPI spec with the actual controllers (multipart payloads, rename/delete endpoints) and wire CI to fail on drift.
  2. Extend mito-web services to cover rename/delete workflows and expose workspace creation/invite once the backend supports it.
  3. Decide on asset file storage (S3, GCS, etc.) or constrain uploads to external URLs; update both API validation and UI affordances accordingly.