Code · Architecture · UX
Project design guide template
Template edition: 3.2.0
Revised: 2026-10-25
Guideline content by Lucas Vitti, licensed under CC BY 4.0. See scope and attribution.
Use this template to document how a project works, why it is structured that way, and what each page or form is for. Keep it in the project's dedicated documentation folder, normally docs/project-design.md, and adapt it to real evidence. Replace placeholders; mark unknowns and proposed choices explicitly. The examples are illustrative and do not describe an audited application's implementation. Use the separate change plan template for approval before implementation and the version journal template for each release's full technical outcome, paired with the separate user changelog template for practical user effects.
Project scope and ownership
- Project: [name and source repository].
- Purpose and users: [problem solved, intended users, and important non-goals].
- Guidelines adopted: [version and date adopted; this template accompanies 3.2.0].
- Documentation owner: [person or team responsible for accuracy].
- Reviewed against: [source revision or release and review date].
- Coverage: [documented areas, known gaps, and staged coverage plan].
- Status: [which parts describe implementation, accepted future design, or proposals].
- Documentation map: [dedicated workspace folder, index linked from the project README, setup, architecture, contracts, UX records, approved plans, technical version journals, user changelogs, decisions, and operations; keep these records under version control].
- Starter provenance: [starter source/version and chosen options if used; generated versus project-owned files and upgrade policy; otherwise not applicable].
Architecture and data flow
Describe the system boundary, its users, and external systems. Then identify the applications, workers, and data stores inside the boundary. Link an editable diagram if it improves understanding; label responsibilities and relationships and explain the diagram in text. Add component detail where necessary, rather than generating every C4 level automatically.
- Important flow: [actor → interaction → application operation → storage/integration → response or feedback].
- State ownership: [request, user/session, process, persistent data, and cleanup responsibilities].
- Trust boundaries: [where identity is verified, authorization is enforced, input is validated, and sensitive data is handled].
- Contracts: [links to API/schema/event definitions, compatibility requirements, and configuration precedence].
- Failure behavior: [timeouts, partial completion, retries, concurrency, and recovery].
- Operations: [links to environment setup, release identity, migrations, rollback, monitoring, and recovery instructions].
Code structure and implementation choices
Repeat a short record for each significant feature/module. Link to real source locations and symbols; do not copy entire files into the guide.
- Feature/module and responsibility: [recognizable product capability and what it owns].
- Entry points and source locations: [actual repository-relative paths and symbols].
- Boundary contract: [public operations, inputs, result and failure shapes, state/data owner, permitted writers, lifecycle/cleanup owner, and side effects].
- Dependency policy: [allowed dependencies and explicit prohibitions; public cross-feature operations versus private internals; narrow capabilities supplied at assembly].
- External adapters: [actual integration details isolated, why isolation is useful, composition point, behavior/capability differences, and authorization/transaction guarantees].
- Pattern used: [e.g. feature module, adapter, repository, component state; or simple direct composition].
- Reason and tradeoff: [problem solved, cost introduced, and why simpler or alternative choices were insufficient].
- Relevant decisions and checks: [decision IDs and test/check locations].
Use the existing project's vocabulary. A short coherent implementation does not need extra layers solely to fill this section. Keep function-level invariants beside the code; explain broader design rationale here.
Internal parameter register
Follow DOC-09. Keep this section as the canonical register for a small project or link docs/parameters.md from here and from each change plan. Record internal policy and behavior values, including unnamed literals and configuration fallbacks, in terms the project owner can understand. Reuse authoritative configuration, schema, and design-token references instead of maintaining competing lists.
- Coverage record: [reviewed source revision, directories/layers, discovery and manual-review method, exclusions, and outstanding coverage gaps with owner and next review scope].
- Parameter and purpose: [stable record ID, plain-language effect, internal identifier or unnamed literal, and actual source path/symbol].
- Value and scope: [current source default or fixed value, type, exact unit, scope such as per file/user/request/process, and observed effective value with environment/date/evidence; unknown observations explicitly unverified].
- Proposed change and state: [proposed value, approval/decision reference, implemented value, release, and deployment state; preserve meaningful distinctions].
- Enforcement and related constraints: [all enforcing modules/routes/layers, smaller external limits, validation rules/allowed range, and rejection or fallback behavior].
- Configuration behavior: [fixed in code or configurable, supported override source and precedence, who may change it, and restart/redeploy requirements; do not imply an override exists without evidence].
- Rationale and ownership: [reason for the value, source of the constraint, policy owner, approval status, and when to review it; unknown rationale recorded as unknown].
- User and change impact: [what users see or cannot do, affected workflows, resource/cost/security/compatibility implications, and dependencies that must be changed together].
- Verification: [source references and planned/completed boundary, validation, fallback, override, and effective-environment checks as relevant; evidence and limitations].
Do not copy credentials or secret values. Cover all planned parameters in a new project; in existing work, declare the actual coverage and staged legacy backlog. A code search alone does not establish completeness. Parameter documentation is a product decision aid; it does not automatically require an administration screen, environment variable, or higher limit.
Example upload limit record
Fictional example only; these values, paths, and outcomes are not verified facts about an existing application.
- Purpose and source: Maximum bytes accepted per uploaded file; PARAM-UPLOAD-01,
UPLOAD_MAX_BYTESinsrc/uploads/upload-policy.ts. - Current source value and scope: 20,971,520 bytes = 20 MiB per file; not a batch-total limit. No deployed value has been inspected. MiB means 1,048,576 bytes; decimal MB means 1,000,000 bytes.
- Proposed value and state: 67,108,864 bytes = 64 MiB, proposed and awaiting owner approval; neither implemented nor deployed. Increasing the limit is a separate behavior change.
- Enforcement and interaction: The proposed server policy rejects files above the limit. Inventory every upload/import entry point and frontend hint; verify proxy request-body and storage limits, including multipart overhead, before claiming the effective maximum is 64 MiB. Those external values are currently unknown in this example.
- Configuration and rationale: Currently proposed as a code constant with no runtime override, so a change would require a release. Record why the original value was chosen; if unknown, say so. The owner must decide whether a fixed limit or supported configuration fits the intended use.
- User and resource impact: Larger files would become eligible only after all constraints are aligned. The plan must account for memory, storage, processing time, and concurrent uploads, and explain the allowed size in help and rejection messages.
- Verification plan: Check one byte below, exactly at, and one byte above the selected limit with disposable fixtures, plus the real request path and an oversized rejection. No checks have run in this fictional record.
Modularity plan and review
Apply ARCH-07 through ARCH-13 within the approved change plan and update this current-state record at completion. In an audit, record the observed structure, violations, and proposed boundaries without changing application code.
- Affected feature and scope: [what is being added or changed; what remains outside this task].
- Module plan: [files/modules, one responsibility each, exposed operations, state owner, and allowed dependencies; identify existing homes to reuse and cohesive units to extract].
- Boundary review: [UI/transport, business policy, persistence, and integration responsibilities; prohibited imports, cycles, private cross-feature access, wide dependency lists, and hidden shared state checked].
- Dependency-check evidence: [command, included source/aliases/dynamic-loading coverage, safe prohibited-dependency fixture result, exceptions; manual review limitations, owner, and revisit trigger if automation is unavailable].
- Change-isolation evidence: [relevant change scenario or test substitute, unrelated features unaffected, and separate real-adapter contract/integration checks].
- Size-check command and convention: [tool/command, full touched-file and function counts excluding blank/comment-only lines, and limitations; use the house 300/50 review thresholds unless a project decision specifies otherwise].
- Measured scope and exclusions: [all new/changed source files and relevant functions; generated/vendor/data-only exclusions and their rationale].
- Oversized item disposition: [exact path/symbol and count; extraction completed or scoped exception, cohesion rationale, alternatives, owner, decision reference, and revisit trigger].
- Before and after: [responsibilities extracted and resulting paths; retain a small coherent implementation when it already satisfies the boundaries].
- Behavior and contract checks: [checks for affected behavior, authorization, failures, and compatibility; outcomes and checks not run].
- Completion status: [resolved findings, exceptions, deferred legacy debt, and any unresolved blocker to declaring the change complete].
Working architecture baseline
- Baseline revision and approved plan: [link to the architecture/UX plan and approval scope].
- Representative feature: [one working path through interaction, application behavior, required persistence/integration, and failure feedback; use an existing feature when appropriate].
- Source and execution: [actual entry points, source modules, safe setup/run commands, and relevant tests].
- What it demonstrates: [boundary direction, ownership, lifecycle, authorization, UX intent, and verification].
- What remains unproven: [other flows, external providers, performance, and existing debt; do not imply complete coverage].
- Reuse: [how the next feature follows this example; starter source/version if the pattern is packaged for reuse].
Keep this proportional to the application. A small script does not need web layers, and an empty directory tree is not a working baseline.
UX structure and shared conventions
Describe the main user journeys, navigation and resource scope, shared components and tokens, content conventions, and accessibility behavior. Record how forms, lists, dialogs, errors, pending work, and unsaved changes behave consistently. Link the shared specifications from individual page records and state exceptions locally.
For each chosen UX pattern, record the problem it solves, applicable UX/VIS rule IDs, implementation choice, tradeoff, and how the result was checked. Avoid unexplained claims such as "modern design" or "Gestalt compliant."
Page and form inventory
List each route or native screen ID and each independently actionable form, including dialogs and drawers. Give each a stable record ID and a link to its details. Reused forms can share a record with all entry points listed. Index labels must say what the user accomplishes, not just name a database entity.
- [PAGE-001]: [route/screen ID] — [one main intent] — [page record location].
- [FORM-001]: [form ID and surface] — [one main intent] — [parent/entry points and record location].
Keep the inventory current as screens are added, removed, or repurposed. For existing projects, identify uncovered screens explicitly rather than implying full coverage.
Page or form record
Repeat this record for each inventory entry. Combine short fields or link shared specifications to keep records readable; use "not applicable" with a reason where appropriate.
- Identity: [record ID, title, route/screen/form ID, and parent or entry points].
- User and scope: [intended actor, permissions, and active account/project/resource].
- Main intent: [one sentence: this page helps the user do X to Y].
- Success condition: [observable completed task, including read-only tasks such as finding and opening the correct record].
- Primary content and supporting controls: [content, search/filter/sort, help, validation, or steps needed for this intent].
- Interaction hierarchy: [global navigation, any single local tab level, destination links, filters, view controls, and object selection; identify exactly what each changes].
- Task and scroll ownership: [active task surface, primary scroll owner, any necessary bounded editor or sibling pane, and why each boundary exists; verify no competing nested mechanisms].
- Separate secondary tasks: [each action, its destination or initially collapsed/on-request surface, and why that surface fits].
- Boundaries: [what is deliberately handled elsewhere; any proposed exception and decision reference].
- Entry and return: [navigation/deep link behavior, cancellation, focus return, preserved search/selection/scroll, and unsaved-work handling].
- States and recovery: [applicable loading, empty, no matches, error, permission denied, pending, saved, failed, conflict, and unavailable states; link shared behavior].
- Accessibility and responsive behavior: [labels, keyboard/focus sequence, announcements, narrow-screen layout, and reduced motion where relevant].
- Choices and rationale: [components/layout, applicable UX/VIS patterns, tradeoffs, and decision IDs].
- Implementation: [source modules, operations/APIs, authoritative permission checks, and relevant contracts].
- Verification: [acceptance criteria, tests or walkthroughs, evidence and revision, results, and checks not run].
- Depth review: [walkthrough of navigation, filtering, scrolling, Back, cancellation, and focus return on desktop, narrow layouts, and keyboard; flag nested tabs/dialogs/scrollers or restyled equivalents].
- Maintenance: [owner, review date/revision, status, and open questions].
Example client consultation page
Illustrative proposed design, not a claim about existing code or verified user behavior.
- Identity: PAGE-CLIENTS, Clients; proposed route
/clients. - Main intent: Help an authorized staff member find and open the correct existing client in the active workspace.
- Success condition: The staff member finds the intended client and opens that client's details.
- Primary content and supporting controls: Searchable client list, relevant identifying fields, and useful sorting/filtering. The active workspace remains clear.
- Secondary task: New client opens FORM-CLIENT-CREATE on request. The registration form is not permanently expanded above the list. A short dialog is proposed because the task is bounded; use a dedicated page if the workflow grows.
- Return and feedback: Cancel restores focus to New client without changing the list. Save confirms the result and provides a way to open the new client. Preserve the search and filters; if the new client does not match, explain that rather than silently clearing the search.
- Patterns: UX-16/17 for task separation, UX-18 for surface choice, VIS-01 for hierarchy, VIS-04 for grouping controls with their affected content.
- Acceptance criteria: On initial load, the list and search are available without moving past a registration form. New client is discoverable. Cancel and save preserve consultation context. Empty, no-match, and failure states remain distinct.
- Implementation and evidence: Not assessed in this example; supply actual module links and verification results before marking the project record implemented or verified.
Example client registration form
Illustrative child record for the preceding example.
- Identity: FORM-CLIENT-CREATE, New client; entered from PAGE-CLIENTS and any other explicitly listed entry points.
- Main intent: Register one new client in the active workspace.
- Success condition: The server confirms creation and returns a client identifier; the interface reports success only then.
- Primary content: The fields actually required by the business contract, their labels/help/errors, and Create client. Cancel supports leaving the task; it is not a second business objective.
- Secondary work: Price configuration belongs to its own client-scoped surface and is offered after creation when relevant. Do not embed a price-management workspace in registration.
- Behavior: Prevent duplicate submission, preserve input after recoverable failure, handle unsaved input deliberately, and use the shared dialog focus and keyboard behavior. Use a page or full-screen presentation if a dialog is unsuitable on mobile.
- Implementation and verification: Link the actual validation and authorization contract. Check failed submission, cancellation, keyboard focus/return, narrow layouts, and successful navigation to the created record. Do not infer those results from a static mockup.
Significant decision record
Use one short record for a consequential architecture, code, security, or UX choice. Use separate files when useful; otherwise stable headings in the guide are sufficient. Adapted from architecture decision records, extended here to UX and implementation choices.
- ID and title: [e.g. DEC-001, Open client registration on request].
- Status and date: [proposed, accepted, superseded, or rejected; date; decision owner/authority].
- Context: [user task or technical problem, evidence, and constraints].
- Options: [meaningful alternatives and their tradeoffs].
- Decision and reason: [selected approach and why it fits this project].
- Consequences: [benefits, costs, risks, compatibility/migration needs, and rejected alternatives worth retaining].
- Affected records: [page/form IDs, modules, contracts, and relevant guideline IDs].
- Verification and revisit condition: [how the outcome will be checked and when the choice should be reconsidered].
- Supersedes or superseded by: [linked decision when applicable].
An accepted decision and an implemented result are different statuses. Keep implementation evidence in the linked guide/page record. Do not invent approval or retroactively claim an undocumented choice was deliberate.
Maintenance and review
Before implementation, provide the architecture and UX change plan and obtain explicit approval for its revision and scope under DOC-07. Record existing approval when it already covers the work; obtain renewed approval for material departures. As part of the same change, reconcile the current design guide with implementation, update links and examples, and finish both changelogs, checking that version, dates, audience, and availability agree. Preserve the approved plan and decision history; remove or mark obsolete current-state instructions. Before deployment, present the outcome and evidence and confirm authorization covers the release and target. Have a reader follow setup or task instructions with safe local data when relevant.
Use Diátaxis to distinguish procedural guidance from factual reference and design explanations. Create a tutorial only when there is a learning need. Publish generic patterns freely when authorized, but keep credentials, real personal data, exploitable findings, and private infrastructure details out of public documentation. Audit-only sessions record proposed corrections in their report and do not edit the project.
References: Diátaxis, C4, and architecture decision records.