Project Planning, Requirements, and Architecture Design

Why Planning Comes Before Code

Every professional software project begins with a planning phase. Writing code before you understand what the system must do, who will use it, and how the pieces connect is one of the most common causes of project failure. In this capstone lesson you will produce three foundational artifacts — a Software Requirements Specification (SRS), a system architecture diagram, and an entity-relationship (ER) diagram — and store them in a version-controlled repository before a single line of application code is written. Employers and clients expect this discipline, and the credentials you are working toward (CompTIA ITF+, CompTIA Linux+, and PCEP Python) all reflect an industry that values structured thinking as much as coding skill.

The Software Requirements Specification

An SRS is a formal document that records what a system must do (functional requirements) and the constraints under which it must operate (non-functional requirements). The widely used IEEE 830 standard provides a template that covers purpose, scope, definitions, overall description, specific requirements, and appendices. You do not need to memorize IEEE 830 section numbers, but you do need every major section present.

Functional requirements describe specific behaviors: "The system shall allow a registered user to reset their password via email link." Each requirement gets a unique identifier (e.g., FR-01) so it can be traced through design, testing, and maintenance.

Non-functional requirements cover performance, security, usability, and legal constraints. Security belongs here explicitly. Reference the OWASP Top Ten (owasp.org) when writing security requirements — this list is the industry-standard baseline for web application threats such as injection, broken authentication, and security misconfiguration. A requirement like "The application shall sanitize all user inputs to prevent SQL injection per OWASP A03" is concrete and testable.

Out-of-scope items are as important as in-scope ones. Documenting what the project will not do protects you from scope creep and helps reviewers give accurate sign-off.

The One-Page Project Proposal

Before writing a full SRS, produce a one-page proposal that captures:

• Target users — who will use the application and what problem it solves for them.
• Core features — the minimum set of functions required for the project to be useful.
• Out-of-scope items — explicitly named features you are deferring or excluding.

This proposal goes through peer and instructor sign-off using a structured checklist. Getting approval at this stage is a professional gate — moving forward without it wastes effort on a direction that may need to change.

System Architecture Diagram

A system architecture diagram shows the major components of your application and how they communicate. For a full-stack web application, this typically includes a client layer (browser), a web/application server, a business logic layer, a database layer, and any external APIs or services. Arrows show the direction of data flow. Label each arrow with the protocol used (HTTP, HTTPS, WebSocket, etc.).

Security note: your diagram should indicate where HTTPS is enforced. Transmitting data over unencrypted HTTP in a production system is a recognized vulnerability. This maps directly to OWASP guidance on security misconfiguration.

The Entity-Relationship Diagram

An ER diagram models the data your application will store. Each entity becomes a database table. Each entity has attributes (columns), one of which is the primary key — a unique identifier for each row. When one table references another, a foreign key column holds the primary key value of the related row. This connection is called a relationship.

Relationships have cardinality: one-to-one, one-to-many, or many-to-many. A many-to-many relationship (for example, students enrolled in courses) requires a junction table with foreign keys pointing to both related tables.

Referential integrity means the database enforces that a foreign key value always matches an existing primary key. Designing for referential integrity at the diagram stage prevents data corruption later.

Use draw.io (free, browser-based) or Lucidchart (free tier) to build your ER diagram. Include table names, all columns, data types where possible, primary key indicators (PK), and foreign key indicators (FK). Walk a classmate through the diagram verbally — explaining your design out loud reveals gaps that silent review misses.

Version Control from Day One

Every artifact — the proposal, SRS, and ER diagram — belongs in version control immediately. Professional teams use Git because it tracks every change, who made it, and why.

Repository setup steps:

1. Create a repository on GitHub or GitLab.

2. Create a `main` branch (production-ready code only) and a `develop` branch (integration branch for ongoing work).

3. Write a README following the Make a README guide (makeareadme.com): include project title, description, installation steps, usage, and license.

4. Commit the SRS and ER diagram as the project's first documented artifacts with a clear commit message such as `docs: add initial SRS and ER diagram`.

This branching strategy (main/develop) is a simplified version of Gitflow, a widely adopted workflow. Feature branches are created from `develop`, merged back after review, and only stable code is merged to `main`.

Safe Working Practices

Web development work is primarily knowledge work at a computer workstation. Ergonomic best practices apply: adjust chair height so your feet are flat on the floor, position the monitor at eye level, and take short breaks to prevent repetitive strain. When storing credentials and API keys during project setup, never commit secrets to a public repository — use environment variables or a `.env` file listed in `.gitignore`. Exposing credentials in version control is a security incident, not just a mistake.