Skip to content

fix: Update README and test checklist for clarity and consistency #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
james-cross merged 1 commit into from
Jun 3, 2025
Merged

fix: Update README and test checklist for clarity and consistency #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
197 changes: 45 additions & 152 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,181 +1,74 @@
# Street Support Platform Web

# Street Support Network – Website Rebuild
![Build Status](https://github.com/streetsupport/streetsupport-platform-web/actions/workflows/ci.yml/badge.svg)
This is the public-facing platform for the Street Support Network. It helps people find local services, share information, and collaborate across the homelessness sector.

This is the future-proof rebuild of the Street Support Network website.
## 🚀 Tech Stack

It provides a modular, maintainable platform to help people experiencing or at risk of homelessness find the support they need. The platform is being rebuilt from the ground up using modern technologies, with a focus on accessibility, sustainability, and long-term maintainability.

---

## 🔧 Core Principles

This project is built with the following principles in mind:

- ✅ **Test-Driven Development (TDD)**
Write unit, integration, and end-to-end tests from the beginning. CI pipelines enforce test passing before deployment.

- ✅ **Mobile-First and Fully Responsive**
Tailwind CSS is used with a mobile-first approach. Layouts scale cleanly with `sm:`, `md:`, `lg:` breakpoints.

- ✅ **Built for the Future**
Uses modern frameworks and tools, avoids deprecated libraries, and prioritises code readability and modularity.

- ✅ **Accessible and Inclusive**
Meets WCAG 2.1 AA. All pages use semantic HTML, keyboard navigation, appropriate contrast, and alt text.

- ✅ **Data-Driven and Impact-Measurable**
Designed to surface insights on usage, service access, and verification timelines through GA4 and event tagging.

---

## 🗂️ Branch Strategy

- `main` – Production-ready, deployable code only
- `staging` – Active development branch. All new features and fixes should branch from here and merge back into staging.

---

## 🚀 Getting Started Locally
- Next.js 15
- React 18
- TypeScript
- Tailwind CSS 4
- Jest + React Testing Library
- JSON-based mock data (used for local development until full CMS/API integration)
- GitHub Actions (CI)
- PowerShell scripts (for development on Windows)

### 1. Fork This Repository
Use the **Fork** button on GitHub.
## 🧪 Testing

### 2. Clone Your Fork
```bash
git clone https://github.com/<your-username>/streetsupport-platform-web.git
cd streetsupport-platform-web
```
This project uses **Jest** and **React Testing Library** for unit and integration tests.

### 3. Set Up Upstream Remote
```bash
git remote add upstream https://github.com/streetsupport/streetsupport-platform-web.git
```
### Running Tests

### 4. Install Dependencies
```bash
npm install
npm run test
```

### 5. Run the Development Server
```bash
npm run dev
```
### Test Setup Highlights

Visit:
```
http://localhost:3000
```
- Babel is configured via `babel.config.json` (not `.js` due to Jest limitations).
- Module path aliases (e.g. `@/components/...`) are resolved using `moduleNameMapper` in `jest.config.cjs`.
- Geolocation and other browser APIs are stubbed or guarded for compatibility.
- The `__mocks__` directory includes mocks for modules like `leaflet` and `react-leaflet`.

---
All tests must pass before merging any pull request into `staging` or `main`.

## 🔄 Keeping Your Fork Up to Date
## 🧱 Admin CMS

```bash
git fetch upstream
git checkout staging
git merge upstream/staging
git push origin staging
```
The admin CMS is developed in a separate repository:
[streetsupport-platform-admin](https://github.com/streetsupport/streetsupport-platform-admin)

---
This manages all partner organisation data and connects to the public platform via API.

## ✅ Deployment
## 📂 Local Development

Deployment is automated via CI/CD:
Mock service data is stored in `data/service-providers.json` and is used by the Find Help search feature.

- `main` → Production
- `staging` → Staging environment
- Preview deployments are created for every PR
To run the project locally:

---

## ⚙️ Contribution Workflow

1. **Branch from `staging`**
```bash
git checkout -b feature/your-feature-name
```

2. **Commit Clearly**
```bash
git commit -m "feat: add filter panel"
```

3. **Push and Open PR**
Target: `streetsupport/streetsupport-platform-web → staging`

4. **Review and Merge**
Reviewed PRs are merged into staging before release to main.

---

## 🛠 Tech Stack

- [Next.js](https://nextjs.org/) (App Router, v15+)
- TypeScript
- Tailwind CSS
- Node.js
- Azure Static Web Apps (planned)
- Google Maps API
- GA4
- WatsonX Virtual Assistant
- JSON-based mock data (temporary until CMS integration)

---

## 📁 Project Structure

```
/src
/app
/api ← Route handlers for mock data (get-services, get-categories)
/[pages] ← Next.js pages and layouts
/components ← UI and layout components (modular)
/data ← Mock data in JSON format
/styles ← Tailwind and legacy SCSS files (migrating gradually)

tailwind.config.js ← Design tokens and theme overrides
postcss.config.js ← Tailwind + PostCSS setup
npm install
npm run dev
```

---

## 📊 Data Model (Temporary)
## 🧭 Project Structure

Data is currently stored as JSON in `/src/data/`:
- `src/components/` – UI components
- `src/contexts/` – React context providers (e.g. `LocationContext`)
- `src/data/` – local JSON data sources for mock services and locations
- `src/pages/` – Next.js pages and routing
- `__mocks__/` – mocks for external libraries used in test environment

- `locations.json`
- `client-groups.json`
- `service-categories.json`
- `service-providers.json`
## 🔄 Git Workflow

Each service provider includes:
- A nested list of services
- A linked category and subcategory
- Postcode, opening hours, and client group support
- Geolocation (latitude, longitude) for map use
See the project instructions for the full GitHub workflow. In short:

Eventually, this will be replaced by dynamic data from the Street Support Network API or CMS.
- Create a new feature branch from `staging`
- Work on that branch
- Create a PR into `streetsupport/streetsupport-platform-web` `staging`
- Merge once tests pass
- Then open a PR from `staging` to `main`
- Finally, sync your fork’s `staging` with upstream

---

## 👥 User Roles (Future CMS)

- **Super Administrator**: Full access
- **Location Administrator**: Manage content in assigned area(s)
- **Organisation Administrator**: Manage their organisation’s data
- **SWEP Administrator**: Control SWEP info and banner visibility
- **Volunteer Administrator**: Read-only access for data comparison

---

## 📄 License

MIT

---

## 🧑‍💻 Maintainers

- [James Cross](https://github.com/James-Cross)
For full developer instructions and context, see the `rebuild-docs.docx` or ask for clarification before making assumptions.
27 changes: 13 additions & 14 deletions test-checklist.ms
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,26 @@ This document tracks key test coverage across the Street Support Network rebuild

## 🧪 Find Help Components

| Component | Status | Notes |
|--------------------|----------|-------|
| `FindHelpEntry` | ✅ Done | Renders with context |
| `FindHelpResults` | ✅ Done | Filter logic, map toggle, empty state |
| `MapView` | ✅ Done | SSR-safe test, renders markers |
| Component | Status | Notes |
|------------------|----------|--------------------------------------------|
| `FindHelpEntry` | ✅ Done | Renders with context |
| `FindHelpResults` | ✅ Done | Filter logic, map toggle, empty state |
| `MapView` | ✅ Done | SSR-safe test, renders markers |
| `FilterPanel` | ✅ Done | Renders filters, user input tested |
| `ServiceCard` | ✅ Done | Renders service data, opening times tested |

## 🔜 Upcoming Test Targets

| Component | Status | Notes |
|----------------------|----------|-------|
| `FilterPanel` | ⏳ TODO | Filter logic response |
| `ServiceCard` | ⏳ TODO | Renders correct data |
| `LocationContext` | ⏳ TODO | Behaviour under different locations |
| Timetable View | 🚧 Planned | Based on rebuild roadmap |
| Geolocation Fallback | 🚧 Planned | Will stub `navigator.geolocation` |
| Component | Status | Notes |
|----------------------|-------------|-------------------------------------------|
| `LocationContext` | ⏳ TODO | Behaviour under different locations |
| Timetable View | 🚧 Planned | Based on rebuild roadmap |
| Geolocation Fallback | 🚧 Planned | Will stub `navigator.geolocation` |

---

## 🔁 Test Strategy

- Test-driven development (TDD) applied where possible
- Components are tested in isolation
- API routes will be mocked during testing
- Leaflet/map components are stubbed to avoid SSR errors
- API routes will be tested using integration suites where applicable