Resolve these points before implementation
What should be included in a web-app specification
A specification exists so that two separate parties — the business paying for the work and the team building it — share the same understanding of what will be delivered. Without it, disputes over scope are almost inevitable.
The core of any web-app specification is a description of what the system must do, organised by process or feature area. Each process should cover who initiates it, what data they provide, what the system does in response, and what the outcome looks like on screen. Vague statements such as "the system will manage customers" are not sufficient. Instead, describe the actual steps: a user creates a customer record by completing these fields, the system validates the data in this way, and the record appears in this list with these columns.
Alongside the happy path, a useful specification sets out the exceptions. What happens if a required field is missing? What happens if a duplicate record already exists? What happens if an integration with a third-party service is unavailable? These edge cases are where most disagreements arise during acceptance testing, so documenting them early saves significant time later.
Integration requirements deserve their own section. For each external system the application must connect to, the specification should state what data flows in which direction, how often, and what happens when the connection fails. The format of that data — whether it is a REST API, a file transfer, or a webhook — does not need to be decided at this stage, but the business rules governing the data exchange do.
Acceptance criteria should be written for each feature or process. These are the conditions that must be met before the business considers the work complete. They should be testable and unambiguous: rather than "the report should load quickly", use "the report must render within a response time the business defines as acceptable, documented in the non-functional requirements".
A common mistake is writing the specification at the wrong level of detail. Too abstract, and developers make assumptions. Too prescriptive, and you constrain sensible technical decisions that do not affect the business outcome. The right balance describes what the system must achieve and the rules it must follow, without dictating how the code is written.
How to define user roles for a web application
Every web application that handles more than one person needs a clear model of who can do what. Defining user roles early prevents both security gaps and costly rework when a new permission requirement surfaces late in the build.
Start by listing every type of person who will log into the system. In a customer portal, this might be an administrator, a support agent, and a customer. In an internal CRM, it might be a sales manager, a sales representative, a marketing user, and a read-only executive. Do not assume that job titles map neatly to system roles — a regional manager in one part of the business may need different permissions from a regional manager in another.
For each role, document what they need to do: which screens they can see, which records they can create, edit, or delete, and which data fields they can view or modify. Pay particular attention to cross-boundary access. Can a sales representative see another representative's leads? Can a customer see only their own orders, or all orders for their organisation? These questions define the data-scoping rules that sit alongside role permissions.
A practical approach is to create a permissions matrix: a table with roles down one axis and actions or data areas across the other, with cells marked as allowed, denied, or conditional. This makes gaps and inconsistencies visible in a way that prose descriptions often do not.
One frequent mistake is creating too many granular roles early on. If you find yourself defining roles like "senior sales representative with reporting access", consider whether a simpler model — fewer roles with additional permission flags — would achieve the same result with less complexity. Over-engineering the role structure at the planning stage makes the system harder to administer and harder to test.
Also plan for the administrative function: who creates and modifies user accounts, who assigns roles, and what happens when someone changes jobs or leaves the organisation. These operational questions are often overlooked until the system is live and an ex-employee still has access.
How to map workflows and processes before building
Mapping workflows means making explicit what currently happens inside people's heads, in spreadsheets, or across email threads. The goal is a shared, testable description of each business process that the application will support.
Begin with the process as it runs today, not as you would like it to run. If the current workflow involves a spreadsheet passed between three people by email, map that exact sequence first. Understanding the existing process — including its workarounds and informal steps — reveals requirements that a clean-room redesign would miss.
For each process, identify the trigger (what starts it), the actors (who is involved at each step), the data (what information is created, updated, or passed on), the decision points (where the path branches depending on a condition), and the outcome (what marks the process as complete). A simple flowchart notation is usually sufficient; the value is in the thinking, not in the diagramming tool.
Then map the exceptions. What happens when someone is absent? What happens when data is incomplete? What happens when a deadline is missed? Exception handling often accounts for more development effort than the main path, yet it is the part most commonly omitted from planning.
Once the current-state processes are mapped, you can identify where the new system should change the workflow. Some changes will be automation — replacing a manual step with a system action. Others will be enforcement — the system prevents a step from being skipped or a rule from being broken. Be explicit about which changes are genuine improvements and which are simply translating the current process into software without benefit.
To verify your workflow maps, walk through them with the people who actually perform the work today. If they spot steps you have missed or conditions you have not considered, the mapping has done its job. A workflow map that has not been validated by operational staff is an assumption, not a specification.
How to plan audit logs for a web application
Audit logs record who did what, when, and to which record. They serve compliance, dispute resolution, and operational investigation. Planning them means deciding what to capture, how long to keep it, and who can see it.
Start by identifying which actions in the system need to be logged. The minimum for most business applications is: user login and logout, creation, modification and deletion of records, changes to user roles and permissions, and exports of bulk data. Beyond that, the decision depends on the sensitivity of the data and the regulatory environment. Financial transactions, access to personal data, and changes to system configuration almost always warrant logging.
For each logged action, record the user identifier, a timestamp, the type of action, the identifier of the affected record, and the before and after values of any changed fields. Storing the full before and after state for every field change can generate significant data volume, so consider whether your application needs field-level detail or whether a summary of what changed is sufficient.
Think carefully about what should not be logged. Passwords, authentication tokens, and sensitive personal data such as medical or financial details should not appear in plain text in audit logs. If the business requirement is to know that a user viewed a particular record, log the access event without copying the record's content into the log.
Retention periods must be defined upfront. Keeping audit logs indefinitely creates storage costs and broadens the scope of any data-subject access request under UK data protection law. Define a retention period that matches your compliance obligations and operational needs, and ensure the system can enforce it automatically.
Access to audit logs themselves needs to be controlled. Typically, only system administrators and compliance or audit staff should be able to view them. Log the fact that someone viewed the audit logs, otherwise you have a blind spot in your own accountability trail.
How to plan notifications and alerts
Notifications tell users that something has happened that requires their attention or informs them of a change. Poorly planned notifications either miss critical events or drown users in noise until they stop reading them entirely.
Begin by listing every event in the system that a user might need to know about. For each event, ask: who needs to know, how quickly do they need to know, and what action might they take in response? A new order placed by a customer might warrant an immediate in-app notification and an email to the fulfilment team. A monthly reporting deadline approaching might warrant an email a week in advance and a reminder the day before.
Classify notifications by urgency and channel. Real-time, high-urgency events — such as a payment failure or a system outage affecting users — may justify in-app alerts and email. Low-urgency, informational events — such as a colleague updating a shared record — are usually better as in-app notifications only, to avoid cluttering inboxes.
Plan user preferences. Where the business allows it, give users control over which notifications they receive and through which channels. This reduces the risk of notification fatigue and respects the user's working patterns. However, distinguish clearly between optional preferences and mandatory notifications that the business requires the user to receive.
Consider aggregation. If a user might trigger or receive dozens of similar events in a short period — for example, a batch import that updates hundreds of records — sending individual notifications for each one is impractical. Plan digest or summary notifications for high-volume scenarios.
Also plan for the absence of expected notifications. If a process is supposed to generate an alert when a certain condition is met and no alert arrives, the system should have a way to detect and flag that failure. Silent notification failures can cause more operational damage than the original event.
How to plan error handling and operational alerts
Error handling and operational alerts are distinct from user notifications. They concern what happens when the system itself encounters a problem — a failed integration, an unexpected data state, or a performance degradation — and how the operations or support team learns about it.
For user-facing errors, the principle is to tell the user something useful without exposing system internals. A message like "We could not process your request. Please try again or contact support" is preferable to a stack trace. Plan the error messages for each major failure scenario: what the user sees, what they can do about it, and what information is logged behind the scenes for the support team.
For system-level errors, define what constitutes an alert-worthy event versus what is simply logged for later review. A single failed login attempt is a log entry. A sustained pattern of failed logins from one IP address may warrant an alert. A payment integration returning errors for three consecutive transactions likely warrants an immediate alert to the operations team.
Plan the alerting channels and escalation paths. Who receives the alert, through what channel (email, Slack, pager-duty-style system), and what happens if the first recipient does not respond within a defined period? An alert that goes unnoticed is no better than no alert at all.
Be specific about what each alert should contain. An alert that says "Error in payment service" forces the recipient to log in and investigate before they can even assess severity. An alert that says "Payment service returned timeout errors on the last three transaction attempts since 14:32, affecting checkout for UK customers" allows the recipient to prioritise immediately.
A common mistake is alerting on everything, which leads to alert fatigue and missed critical events. Start with a conservative set of alerts for genuinely urgent problems, then add more as the team develops confidence in what constitutes a useful signal. Review alert configurations periodically — what was useful at launch may become noise as the system matures.
How to decide between a prototype and a full build
A prototype is a partially built version of the application used to test assumptions before committing to a full build. Deciding whether to invest in one depends on what is uncertain about the project.
Prototypes are most valuable when the core risk is not technical but conceptual. If you are unsure whether users will adopt a particular workflow, whether a new process will actually save time, or whether a proposed interface makes sense to the people who will use it, a prototype allows you to test that with real users before building the full system. The cost of changing direction on a prototype is a fraction of the cost of reworking a completed application.
Prototypes are less valuable when the requirements are well understood and the primary risk is execution. If you are replacing a known system with a modern version that does the same thing, or building an internal tool where the processes are already documented and agreed, a prototype may add cost and delay without providing new information.
Be clear about what a prototype is and is not. It is not a half-finished production system. It typically omits error handling, security hardening, audit logging, and production-grade infrastructure. Building a prototype that is effectively a full system in disguise is a common way to overspend without realising it.
Agree upfront what will happen after the prototype. If the prototype validates the approach, does the full build start from the prototype's code or from scratch? Reusing prototype code can accelerate the build, but only if the prototype was built with production standards in mind — which, as noted, it usually is not. Document this decision before the prototype begins, otherwise the transition becomes a negotiation.
Set a fixed scope and duration for the prototype phase. Without a clear boundary, prototype work has a tendency to expand into a de facto build. Define which questions the prototype must answer, what the team will show at the end, and what the decision criteria are for proceeding to a full build.
Functional vs non-functional requirements for web apps
Functional requirements describe what the system does. Non-functional requirements describe how well it does it. Both must be planned, but they are often treated differently — functional requirements are usually documented explicitly, while non-functional requirements are assumed or left implicit until they cause problems.
Functional requirements cover the features and processes: a user can create a customer record, the system generates an invoice, an administrator can assign roles. These are typically the easiest part of planning because they map directly to business activities.
Non-functional requirements cover performance, security, availability, scalability, and usability. Examples include: the system must respond to a standard search query within two seconds, the system must be available 99.5% of business hours, the system must support concurrent use by 200 staff members without degradation, and the system must encrypt personal data at rest.
The reason non-functional requirements matter is that they constrain the technical approach and the infrastructure, which in turn affects cost and timeline. A system that must handle 50 concurrent users has different infrastructure requirements from one that must handle 5,000. A system that must retain audit logs for seven years has different storage and data-management requirements from one with a 90-day retention period. If these constraints are not stated upfront, the build team will make assumptions that may not match the business's actual needs.
A practical approach is to define non-functional requirements in categories: performance (response times, throughput), availability (uptime targets, maintenance windows), security (authentication, encryption, access control standards), scalability (expected user growth, data volume growth), and compliance (data protection, industry-specific regulations). For each category, state what the business requires and, where relevant, how it will be measured.
Avoid the temptation to set every non-functional requirement at the highest possible level. "The system must never go down" is not a useful requirement. "The system must be available during UK business hours with planned maintenance windows communicated 48 hours in advance" is specific and testable. Over-specifying non-functional requirements drives up cost without necessarily delivering business value.
Review non-functional requirements with the build team before the project starts. Some requirements may be straightforward to achieve; others may require specific architectural decisions or third-party services. Understanding this early allows the business to make informed trade-offs between capability, cost, and timeline rather than discovering constraints during the build.