Digital Platform Specification Template

A website shows information; a platform manages people, data and decisions. Once you have users in different roles (who registers, who approves, who sees what), any ambiguity in the spec later becomes a permissions bug or a data leak. AI tools can now write much of the code, but they cannot decide for you who may delete a registration or see a phone number. This template forces you to make those decisions in writing before the first line of code.

How to use the template

The template

1) Overview
   Problem: [what happens today and why it is costly, slow or unfair]
   For whom: [roles in brief]
   Success after 3 months means: [observable outcomes]
   Not a goal: [what the platform will not do]

2) Roles
   For each role: name | who they are | what they want |
   how they get the role (self sign-up, invitation, assignment)

3) Permissions matrix
   Rows = actions on each entity, columns = roles
   Values: yes | no | own only | with approval

4) Entities and data
   For each entity: fields | required? | sensitive? | owner |
   relation to other entities | retention period

5) Workflows
   For each workflow: trigger | steps in order | who performs each step |
   notifications | what if it fails

6) States and transitions
   For each entity with a lifecycle: states | allowed transitions |
   who triggers them | what happens

7) First-version scope
   Must have now | Later | Will not do

8) Integrations
   Service | purpose | data direction | account owner | what if it stops

9) Non-functional requirements
   Languages and direction | accessibility | security and sign-in | backups
   | audit log | expected performance | devices

10) Risks
   Risk | likelihood | impact | mitigation | owner

11) Backlog
   As a [role] I want [action] so that [benefit]
   + acceptance criteria + priority + stage

12) Open questions and decisions log
   Question | who answers | due date | decision | date

The hardest sections, explained

Roles

A role is a set of permissions, not a person. One person can hold two roles (coordinator and trainer, for example). Start with as few roles as possible; every extra role multiplies testing. For each role ask: how does a user get it? Self sign-up suits a participant, but an admin role must be assigned, not requested.

Permissions matrix

The most common security flaws in platforms are not sophisticated attacks but permissions nobody thought about: a user changes a number in the URL and sees another user's data. The matrix turns every action on every entity into a written decision. Pay special attention to "own only": it must be checked on the server, not just in the interface.

States

Every entity that moves through stages (registration: pending, confirmed, cancelled…) needs a state diagram: which states, which transitions are allowed, and who triggers them. Unwritten transitions become bugs: can a cancelled registration be confirmed? Can a certificate be issued to someone who never attended?

First-version scope

The first version should serve the core workflow end to end, even in its simplest form, rather than half-serve five workflows. Anything that can be done manually at first (a sheet, a message, a phone call) does not need automation in version one.

Risks

Write your project's real risks, not a generic list: sensitive data, dependence on one person, an external service whose terms may change, users without smartphones, AI-generated code nobody reviewed.

A prompt to critique the spec

You are a strict systems analyst.
Below is the spec for a platform [short description].
Do not add features or suggest technologies. Only list:
1) Contradictions between roles, the permissions matrix and the workflows.
2) Missing or dangerous state transitions (e.g. what if cancelled after confirmation?).
3) Data collected without a clear reason, or sensitive data with no stated protection.
4) Workflow actions that no role has permission to perform.
5) Five questions the project owner must answer before starting.
Order findings from most to least serious. Do not flatter.
Spec: [paste text after removing any personal data or keys]

Completed example

Completion checklist

• Problem, success and non-goals are written in the overview.
• Every role has a description and a way of being obtained.
• The permissions matrix covers every action on every entity and was reviewed with role representatives.
• Entities are documented with fields, sensitivity and retention.
• The core workflow is written end to end, including the failure case.
• The state diagram defines what is allowed and what is forbidden.
• First-version scope is split into now, later and will not do.
• Risks are specific to the project, each with an owner.
• User stories have testable acceptance criteria.
• Open questions have someone to answer them and a date.
• The spec has had a critical review and is signed off by the decision-maker.