Build in public. Inspire the community.

MzansiBuilds is a platform that helps developers build publicly and keep up with what other developers are building. Developers can share projects, post milestones, collaborate, comment on each other's work, and get celebrated when they ship.

• Overview
• Architecture
• Tech stack
• Getting started
• Environment variables
• Running tests
• API reference
• UML diagrams
• AI usage
• Contributing
• License

MzansiBuilds supports the following user journeys:

1. Account management — developers register, log in, and manage their profile.
2. Project creation — create a project with a title, description, tech stack, current stage, and support required.
3. Live feed — browse a real-time feed of what the community is building, with live updates via Server-Sent Events.
4. Collaboration — comment on any project or raise a hand to request collaboration.
5. Milestones — continuously log progress milestones against a project.
6. Celebration Wall — completing a project adds the developer to a shared Celebration Wall.

mzansibuilds/
├── client/                   # React + TypeScript (Vite) — frontend SPA
│   ├── src/
│   │   ├── __tests__/        # Component, page, context, and service tests
│   │   ├── components/       # Navbar, ProjectCard, Footer
│   │   ├── context/          # AuthContext (JWT state)
│   │   ├── pages/            # Feed, Landing, Login, Register, NewProject, CelebrationWall
│   │   ├── services/         # Axios API client + SSE stream helper
│   │   └── types/
│   └── ...
├── server/                   # Node.js + Express + TypeScript — REST API
│   ├── src/
│   │   ├── __tests__/        # Route integration tests
│   │   ├── data/
│   │   │   └── store.ts      # JSON file-based data store (data.json)
│   │   ├── middleware/
│   │   │   └── auth.middleware.ts
│   │   ├── routes/
│   │   │   ├── auth.ts
│   │   │   └── projects.ts
│   │   ├── lib/
│   │   │   └── sseBroker.ts  # SSE connection manager
│   │   ├── app.ts
│   │   └── index.ts
│   └── ...
├── docs/
│   └── uml/                  # Use-case, class and sequence diagrams
└── .github/
    └── workflows/
        └── ci.yml

Key architectural decisions:

• REST API for CRUD operations; Server-Sent Events (SSE) for real-time project updates (new comments, collaboration requests).
• JWT-based authentication with short-lived access tokens.
• JSON file persistence via data.json (managed by server/src/data/store.ts) — no external database required to run locally.
• All secrets injected via environment variables — never hardcoded.

• Node.js ≥ 18
• npm ≥ 9

# Clone the repository
git clone https://github.com/YOUR_USERNAME/mzansibuilds.git
cd mzansibuilds

# Install backend dependencies
cd server && npm install

# Install frontend dependencies
cd ../client && npm install

cd server
cp .env.example .env   # fill in your values

# Terminal 1 — backend (hot reload)
cd server && npm run dev

# Terminal 2 — frontend (hot reload)
cd client && npm run dev

The API runs on http://localhost:5000 and the frontend on http://localhost:5173.

Note: A data.json file will be created automatically in the project root the first time the server starts. This file acts as the local database — do not commit it.

Copy .env.example to .env inside the server/ directory and fill in the values. Never commit .env.

The frontend reads one variable (set in client/.env):

cd server
npm test                  # run all tests
npm run test:coverage     # with coverage report

cd client
npm test                  # run all component tests
npm run test:coverage

Tests follow a strict Red → Green → Refactor TDD cycle. Every route and core component has a corresponding test file. Rate limiting is automatically disabled in the test environment (NODE_ENV=test), so auth route tests will never produce false 429 responses. CI enforces that no code merges to main unless all tests pass.

Valid stage values: planning · building · testing · launched · completed

Events emitted by the server:

The frontend openProjectStream(projectId, opts) helper in client/src/services/api.ts wraps the native EventSource API and returns a cleanup function suitable for use in a useEffect hook.

Diagrams are stored in /docs/uml/.

• use-case.png — all actor interactions with the system
• class-diagram.png — entity model (Developer, Project, Milestone, Comment, CollabRequest)
• sequence-diagram.png — project creation → SSE broadcast → milestone update flow

MzansiBuilds uses an AI language model to power smart project tag suggestions when a developer creates or edits a project.

What data is sent: Only the project title and description text. No personal information, passwords, or private data is transmitted to the AI provider.

Transparency: The AI suggestion feature is clearly labelled in the UI. Users can ignore or override any suggestion.

Full policy: See docs/ai-ethics.md for our complete AI ethics and responsible use documentation.

1. Fork the repo and create a feature branch: git checkout -b feature/your-feature
2. Write tests first (TDD — Red → Green → Refactor)
3. Commit using Conventional Commits: feat:, fix:, chore:, test:, docs:
4. Open a pull request against main — CI must be green before merge

MIT © 2026 MzansiBuilds