Sprint 3 Review & Documentation

Session Timeline

Learning Objectives

• Understand different types of technical documentation
• Write effective README files
• Create architecture diagrams that communicate system design
• Document APIs with clear examples
• Maintain decision logs (ADRs - Architecture Decision Records)
• Write setup and deployment instructions
• Document code with meaningful comments
• Evaluate project progress and quality

Why Documentation Matters

Documentation Helps:

• New Team Members: Get up to speed quickly
• Future You: Remember why you made decisions
• Stakeholders: Understand what was built
• Users: Know how to use the system
• Maintenance: Easier to fix and extend

Types of Documentation

1. User Documentation:

• README - Project overview and quick start
• User guides - How to use features
• FAQ - Common questions

2. Developer Documentation:

• Setup instructions - How to run locally
• Architecture docs - System design
• API documentation - Endpoint specs
• Contributing guidelines - How to contribute

3. Project Documentation:

• Decision logs (ADRs) - Why we chose X
• Meeting notes - Team discussions
• Retrospectives - Sprint learnings

Writing an Excellent README

Essential Sections:

1. Project Title & Description: What it does (1-2 sentences)
2. Screenshot/Demo: Show don't just tell
3. Features: Bullet list of main capabilities
4. Tech Stack: Languages, frameworks, tools
5. Getting Started: Prerequisites and installation
6. Usage: How to use/run the app
7. Team: Who built it
8. License: MIT, Apache, etc.

README Example

# StudySpace Finder

A web application that helps students find and book available study spaces across campus in real-time.

![Screenshot of app](docs/screenshot.png)

## Features

- 🔍 Search study spaces by building and capacity
- 📅 Real-time availability updates
- 🔐 Secure user authentication
- 📊 Admin dashboard for space management

## Tech Stack

**Frontend:** React 18, TypeScript, Material-UI  
**Backend:** Node.js, Express, PostgreSQL  
**Hosting:** Heroku

## Getting Started

### Prerequisites
- Node.js 16+
- PostgreSQL 14+

### Installation

```bash
# Clone repository
git clone https://github.com/your-team/studyspace-finder.git
cd studyspace-finder

# Install dependencies
npm install

# Setup database
createdb studyspace_db
npm run migrate

# Start development server
npm run dev
```

Visit http://localhost:3000

## Team

- Tom Johnson - Frontend Lead
- Bob Smith - Backend Lead
- Charlie Davis - Database & DevOps

## License

MIT

Architecture Documentation

Include:

• High-Level Diagram: Visual of system components
• Component Descriptions: What each part does
• Data Flow: How data moves through system
• Technology Choices: Why you chose each technology
• External Dependencies: APIs, libraries, services

Example Architecture Diagram

# System Architecture

## High-Level Overview

```
┌──────────────┐         ┌──────────────┐         ┌──────────────┐
│              │  HTTPS  │              │   SQL   │              │
│   React      │ ◄─────► │   Express    │ ◄─────► │  PostgreSQL  │
│   Frontend   │         │   Backend    │         │   Database   │
│              │         │              │         │              │
└──────────────┘         └──────┬───────┘         └──────────────┘
                                 │
                                 │ HTTPS
                                 ▼
                        ┌──────────────┐
                        │  Google Maps │
                        │     API      │
                        └──────────────┘
```

## Components

### Frontend (React)
- User interface for searching and booking spaces
- Built with Material-UI components
- State management with React Context

### Backend (Express)
- REST API endpoints
- User authentication with JWT
- Business logic for bookings

### Database (PostgreSQL)
- Stores users, spaces, bookings
- Normalized schema
- Indexes on frequently queried fields

API Documentation

## GET /api/spaces

Get list of all study spaces.

**Query Parameters:**
- `building` (string, optional) - Filter by building name
- `capacity` (number, optional) - Minimum capacity

**Response:** 200 OK
```json
{
  "spaces": [
    {
      "id": 1,
      "name": "Room 204",
      "building": "Library",
      "capacity": 6,
      "available": true
    }
  ]
}
```

**Example Request:**
```bash
curl https://api.example.com/spaces?building=Library&capacity=4
```

**Errors:**
- `400` - Invalid parameters
- `500` - Server error

Architecture Decision Records (ADRs)

When to Write an ADR:

• Choosing tech stack (React vs Vue)
• Architectural patterns (REST vs GraphQL)
• Database choices (SQL vs NoSQL)
• Third-party services (Stripe vs PayPal)

Example ADR

# ADR 001: Use PostgreSQL for Database

**Date:** 2024-10-15  
**Status:** Accepted

## Context

Our application needs to store user accounts, study spaces, and bookings. 
These entities have clear relationships (users → bookings → spaces), and 
we need strong data consistency to prevent double-booking.

## Decision

We will use PostgreSQL as our database.

## Alternatives Considered

1. **MongoDB (NoSQL):** Good for flexible schemas, but we have fixed structure
2. **Firebase:** Easy setup, but vendor lock-in and limited querying
3. **MySQL:** Similar to PostgreSQL, but Postgres has better JSON support

## Consequences

### Positive
- ACID transactions prevent booking conflicts
- Foreign keys ensure data integrity
- Team has PostgreSQL experience
- Free tier on Heroku

### Negative
- More complex setup than Firebase
- Need to run migrations for schema changes
- Requires SQL knowledge

Writing Clear Setup Instructions

Good Setup Instructions Include:

• Exact versions of tools (Node 16, Python 3.9)
• OS-specific instructions if needed (Windows vs Mac)
• Step-by-step commands to run
• Environment variables to set (.env.example)
• How to verify setup worked
• Common troubleshooting tips

Code Comments: When and How

// Increment i
i++;

// Check if user is null
if (user === null) {
  // Return error
  return error;
}

// HACK: parseFloat returns NaN for "5%"
// so we strip the % first
const value = parseFloat(str.replace('%', ''));

// NOTE: Must validate email before 
// calling sendVerification, otherwise
// API returns 500 instead of 400
validateEmail(user.email);
sendVerificationEmail(user);

// TODO: Extract to config file
const MAX_RETRIES = 3;

Part B: Create Project Documentation

Sprint Goals:

• Update/create comprehensive README
• Document system architecture
• Write API documentation for key endpoints
• Create setup.md with step-by-step instructions
• Write 1-2 ADRs for important decisions
• Add code comments where needed

Creating Architecture Diagrams

Tools for Diagrams:

• Draw.io / diagrams.net: Free, web-based, saves as .png or .svg
• Lucidchart: Professional, has free tier
• Mermaid: Text-based diagrams in markdown
• ASCII Art: Simple text diagrams

```mermaid
graph TD
    A[User] -->|HTTPS| B[React Frontend]
    B -->|API Calls| C[Express Backend]
    C -->|SQL| D[PostgreSQL]
    C -->|API Call| E[Google Maps API]
```

Documenting Database Schema

# Database Schema

## Tables

### users
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | SERIAL | PRIMARY KEY | Unique user ID |
| email | VARCHAR(255) | UNIQUE, NOT NULL | User email |
| password_hash | VARCHAR(255) | NOT NULL | Bcrypt hashed password |
| created_at | TIMESTAMP | DEFAULT NOW() | Account creation date |

### spaces
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | SERIAL | PRIMARY KEY | Unique space ID |
| name | VARCHAR(100) | NOT NULL | Space name (e.g., "Room 204") |
| building | VARCHAR(100) | NOT NULL | Building name |
| capacity | INTEGER | CHECK > 0 | Max occupancy |

### bookings
| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| id | SERIAL | PRIMARY KEY | Unique booking ID |
| user_id | INTEGER | FOREIGN KEY → users(id) | Who booked |
| space_id | INTEGER | FOREIGN KEY → spaces(id) | Which space |
| start_time | TIMESTAMP | NOT NULL | Booking start |
| end_time | TIMESTAMP | NOT NULL | Booking end |

Deployment Documentation

# Deployment Guide

## Heroku Deployment

### Prerequisites
- Heroku account
- Heroku CLI installed

### Steps

1. **Create Heroku app**
   ```bash
   heroku create your-app-name
   ```

2. **Add PostgreSQL**
   ```bash
   heroku addons:create heroku-postgresql:hobby-dev
   ```

3. **Set environment variables**
   ```bash
   heroku config:set NODE_ENV=production
   heroku config:set API_KEY=your_key_here
   ```

4. **Deploy**
   ```bash
   git push heroku main
   ```

5. **Run migrations**
   ```bash
   heroku run npm run migrate
   ```

6. **Verify**
   Visit https://your-app-name.herokuapp.com

Contributing Guidelines

Include:

• Coding Standards: Naming conventions, style guide
• Git Workflow: Branch naming, commit message format
• Pull Request Process: How to create and review PRs
• Testing Requirements: What tests are needed
• Code Review Checklist: What reviewers check

Project Self-Evaluation

Evaluate Your Project:

Documentation Completeness Checklist

Before submitting project:

• ✓ README.md is comprehensive and up-to-date
• ✓ Architecture diagram exists and is clear
• ✓ Setup instructions tested by teammate
• ✓ API endpoints documented with examples
• ✓ Database schema documented
• ✓ Important decisions captured in ADRs
• ✓ Code has meaningful comments
• ✓ .env.example file with all required variables
• ✓ License file included
• ✓ No broken links in documentation

Before Next Lecture

1. Complete Documentation:
   • Finish all planned documentation
   • Get peer review from teammate
   • Fix any unclear sections
2. Test Setup Instructions:
   • Have teammate follow setup.md on fresh computer
   • Fix any missing steps or errors
3. Organize docs/ Folder:
   • Create clear folder structure
   • Link all docs from README
4. Submit to Moodle:
   • Link to repository (ensure docs are pushed)
   • Link to key documentation files
5. Prepare for Presentation:
   • Think about what to present
   • What's most impressive about your project?