SCSA Issue Tracker

Project-based collaboration tool for issues, members, comments, notifications, dashboards, and project-member real-time chat.

The project started as an issue tracker for SCSA training teams, but the architecture is closer to a small collaboration SaaS foundation: authentication, project membership, role-based access, task/issue flow, activity tracking, and realtime messaging.

Live Demo

• Frontend: https://scsa-issue-tracker.vercel.app
• Backend health: https://scsa-issue-tracker-api.onrender.com/api/health

Render free instances may sleep after inactivity. Open the health URL once before a demo.

What It Does

• Account signup and JWT login
• Project creation and project-member management
• OWNER/MEMBER role control
• Issue CRUD with status, priority, assignee, due date, search, and filters
• Board/list/table issue views
• Comments, replies, markdown content, and emoji reactions
• Notifications with read/delete handling
• My-work dashboard with status, priority, deadline, and activity summaries
• Project-member-only realtime chat over STOMP WebSocket
• Production deployment with Vercel, Render, PostgreSQL, Docker, and Flyway

Architecture

flowchart LR
  Browser["React/Vite Frontend<br/>Vercel"] -->|HTTP /api/v1 via rewrite| API["Spring Boot API<br/>Render"]
  Browser -->|WSS /ws direct| WS["STOMP WebSocket<br/>Render"]
  API --> DB["Render PostgreSQL"]
  WS --> DB
  API --> Flyway["Flyway migrations"]

Loading

The frontend uses relative HTTP API paths (/api/v1/...) and Vercel rewrites them to Render. WebSocket connects directly to Render because Vercel rewrites are not a reliable WebSocket upgrade proxy.

Tech Stack

Area	Stack
Frontend	React 18, Vite, React Router, STOMP.js, Marked, DOMPurify
Backend	Java 17, Spring Boot 3.5, Spring Security, JPA, Bean Validation
Auth	JWT Bearer token, BCrypt password hashing
Realtime	Spring WebSocket/STOMP, project-member authorization
Database	PostgreSQL in production, Oracle XE-compatible local migrations
Migration	Flyway
Deployment	Vercel frontend, Render backend, Render PostgreSQL, Docker

Repository Structure

scsa-issue-tracker/
|-- backend/                 Spring Boot API server
|-- frontend/                React/Vite frontend app
|-- docs/                    Architecture, deployment, API, and decision notes
|   |-- decisions/           Small ADR-style implementation decisions
|   `-- sql/                 Manual reference SQL
|-- README.md
`-- .gitignore

Branch Strategy

Branch	Purpose
frontend-dev	Vercel production branch
backend-dev	Render production branch
main	Integrated portfolio/archive branch

Frontend work is merged into frontend-dev; backend work is merged into backend-dev. main is periodically synchronized so GitHub visitors see the current integrated project.

Local Setup

Backend

cd backend
./gradlew bootRun

Windows:

cd backend
gradlew.bat bootRun

Default backend URL:

http://localhost:8081

Frontend

cd frontend
npm install
npm run dev

Default frontend URL:

http://localhost:5173

Local frontend requests are proxied to localhost:8081 by frontend/vite.config.js.

Production Notes

Required backend environment variables:

SPRING_PROFILES_ACTIVE=prod
DB_URL=jdbc:postgresql://...
DB_USERNAME=...
DB_PASSWORD=...
JWT_SECRET=...
CORS_ALLOWED_ORIGINS=https://scsa-issue-tracker.vercel.app

Optional frontend environment variable:

VITE_WS_URL=wss://scsa-issue-tracker-api.onrender.com/ws

See Deployment and Production Runbook for the full operational notes.

Documentation

• Architecture
• API Contract
• Database and Migrations
• Deployment
• Production Runbook
• Security Decisions
• Roadmap
• Demo Scenario

Decision notes:

• Branch and Deployment Strategy
• Project Chat WebSocket
• Database Migration Strategy

Engineering Highlights

• Server-side ownership and membership checks prevent clients from choosing arbitrary userId, reporterId, or authorId.
• Issue status changes use a dedicated endpoint, keeping intent separate from general issue edits.
• PostgreSQL production schema is managed by Flyway and validated by JPA.
• Realtime chat requires both JWT authentication and project membership authorization.
• The frontend keeps API calls centralized through a fetch client, auth context, and typed domain modules.
• Deployment uses separate frontend/backend production branches to avoid frontend/backend release coupling during iteration.

Reusable Foundation

The project can be reused as a starting point for future services that need:

• User authentication
• Organization/project membership
• Role-based access control
• Task or issue workflows
• Comments and reactions
• Notifications
• Realtime project chat
• Dashboard-style work summaries
• Vercel/Render/PostgreSQL deployment

License

No license has been selected yet. Treat the code as private/portfolio reference unless a license is added.