OpenAPI 3.1, Prisma Schema, and Mermaid Diagrams: All from One AI Prompt

#openapi #prisma #ai #devtools

When you start a new backend project, you need several things to be true simultaneously: the API contract needs to match the database schema, the database schema needs to match the data model in your head, and your diagrams need to reflect all of the above. In practice, these three artifacts drift apart almost immediately — because they're authored in different tools, at different times, by different people.

8sprint takes a different approach: generate all three from a single plain-English description, using specialized AI agents that coordinate with each other to ensure the outputs are consistent by construction.

Here's what that looks like for a real project.

The Prompt

Suppose you're building a multi-tenant SaaS platform for managing marketing campaigns. You describe it like this:

"Multi-tenant marketing campaign platform. Organizations have members with roles (owner, admin, editor, viewer). Organizations run campaigns with start/end dates, budget, and status. Campaigns contain ad groups, which contain individual ads with creative content, targeting parameters, and performance metrics. Need audit logging on all state changes."

That's 57 words. Here's what 8sprint generates from it.

The OpenAPI 3.1 Spec

8sprint produces a complete API contract covering authentication, CRUD operations, tenant isolation, and role checks. Here's a representative excerpt:

openapi: 3.1.0
info:
  title: Campaign Management API
  version: 1.0.0

components:
  schemas:
    Campaign:
      type: object
      required: [id, organizationId, name, status, startDate]
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 255
        status:
          type: string
          enum: [draft, scheduled, active, paused, completed, archived]
        startDate:
          type: string
          format: date
        endDate:
          type: [string, "null"]
          format: date
        budget:
          type: [number, "null"]
          minimum: 0
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    AuditLog:
      type: object
      properties:
        id:
          type: string
          format: uuid
        entityType:
          type: string
          enum: [campaign, ad_group, ad]
        entityId:
          type: string
          format: uuid
        action:
          type: string
          enum: [created, updated, status_changed, deleted]
        actorId:
          type: string
          format: uuid
        changes:
          type: object
          additionalProperties: true
        createdAt:
          type: string
          format: date-time

paths:
  /campaigns:
    get:
      operationId: listCampaigns
      summary: List campaigns for the authenticated organization
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [draft, scheduled, active, paused, completed, archived]
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Paginated campaign list

A few things worth noting in this spec:

Nullable fields use type: [X, "null"] — the OpenAPI 3.1 way to express nullable values, using JSON Schema's type union syntax instead of the nullable: true keyword from OpenAPI 3.0
Standard number formats — OpenAPI defines float and double as standard formats; decimal is not in the specification
AuditLog uses polymorphic entityType/entityId — covers campaigns, ad groups, and ads in a single table without per-entity foreign keys, keeping the design clean and extensible

The spec includes security definitions for JWT bearer auth, tenant-scoped filtering on all list endpoints, and proper response schemas for validation errors — not just the happy path.

The Prisma Schema

Simultaneously, 8sprint generates a Prisma schema that maps directly to the OpenAPI data model:

model Organization {
  id        String   @id @default(uuid())
  name      String
  slug      String   @unique
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  members   OrganizationMember[]
  campaigns Campaign[]
}

model OrganizationMember {
  id             String   @id @default(uuid())
  organizationId String
  userId         String
  role           MemberRole
  createdAt      DateTime @default(now())

  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)

  @@unique([organizationId, userId])
  @@index([userId])
}

enum MemberRole {
  owner
  admin
  editor
  viewer
}

model Campaign {
  id             String         @id @default(uuid())
  organizationId String
  name           String
  status         CampaignStatus @default(draft)
  startDate      DateTime
  endDate        DateTime?
  budget         Decimal?
  createdAt      DateTime       @default(now())
  updatedAt      DateTime       @updatedAt

  organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
  adGroups     AdGroup[]
  auditLogs    AuditLog[]

  @@index([organizationId, status])
  @@index([organizationId, startDate])
}

enum CampaignStatus {
  draft
  scheduled
  active
  paused
  completed
  archived
}

model AuditLog {
  id         String   @id @default(uuid())
  entityType String
  entityId   String
  action     String
  actorId    String
  changes    Json     @default("{}")
  createdAt  DateTime @default(now())

  @@index([entityType, entityId])
  @@index([actorId])
}

Notice the alignment: the CampaignStatus enum in Prisma matches the OpenAPI enum exactly. The AuditLog model uses a clean polymorphic design — entityType and entityId are sufficient to reference any entity type (campaign, ad group, or ad) without needing per-entity foreign keys. The indexes on organizationId, status and organizationId, startDate support the filtering and sorting patterns the API spec defines.

This isn't coincidence. The agents that generate the OpenAPI spec and the Prisma schema coordinate through a shared internal representation of your data model, so the outputs stay in sync.

The Mermaid Diagrams

8sprint also produces Mermaid diagrams for your README and architecture documentation. The ER diagram for this project:

erDiagram
    Organization {
        uuid id PK
        string name
        string slug
        datetime createdAt
    }
    OrganizationMember {
        uuid id PK
        uuid organizationId FK
        uuid userId FK
        enum role
    }
    Campaign {
        uuid id PK
        uuid organizationId FK
        string name
        enum status
        date startDate
        date endDate
        decimal budget
    }
    AdGroup {
        uuid id PK
        uuid campaignId FK
        string name
        boolean active
    }
    Ad {
        uuid id PK
        uuid adGroupId FK
        string creativeUrl
        json targetingParams
        json performanceMetrics
    }
    AuditLog {
        uuid id PK
        string entityType
        uuid entityId
        string action
        uuid actorId
        json changes
    }

    Organization ||--o{ OrganizationMember : "has"
    Organization ||--o{ Campaign : "runs"
    Campaign ||--o{ AdGroup : "contains"
    AdGroup ||--o{ Ad : "contains"

This renders directly in GitHub READMEs and any tool that supports Mermaid — Notion, Confluence, GitLab, and most modern documentation platforms.

Beyond the ER diagram, 8sprint generates sequence diagrams for key flows. Here's the campaign status transition flow:

sequenceDiagram
    actor Client
    participant API
    participant DB
    participant AuditService

    Client->>API: PATCH /campaigns/{id} {status: "active"}
    API->>API: Validate role (admin+)
    API->>DB: Check campaign exists and belongs to org
    DB-->>API: Campaign record
    API->>DB: UPDATE campaign SET status = 'active'
    DB-->>API: Updated campaign
    API->>AuditService: Log(entityType: campaign, action: status_changed)
    AuditService->>DB: INSERT audit_log
    API-->>Client: 200 OK {campaign}

The Full Package

Beyond these three core artifacts, 8sprint also generates:

README.md — project overview, setup instructions, environment variables
API Guide — authentication flow, pagination conventions, error format
Data Dictionary — definitions for every field in the schema
Error Catalog — all error codes and their meanings
Deployment Checklist — environment setup, database migration steps

All of this from one prompt, in under 3 minutes.

Why Synchronized Outputs Matter

The real value isn't the individual artifacts — it's that they start synchronized. When an OpenAPI spec and a Prisma schema are written by different people at different times, mismatches are inevitable: a field that's required in the spec is nullable in the database, an enum value that exists in the schema doesn't appear in the API response, a foreign key that should cascade doesn't.

Starting from a single generated source means these inconsistencies are caught before a line of application code is written. You still need to review the outputs — the AI can misinterpret requirements, and you know your project better than any model does. But the baseline is coherent, and reviewing a coherent baseline is much faster than reconciling three independently authored documents.