Citizen Reporting System

A distributed, microservices-based citizen reporting platform built with Go, React, and event-driven architecture.

Table of Contents

• Overview
• Architecture
• Tech Stack
• Prerequisites
• Quick Start
• Detailed Setup
• Running the Application
• Development
• Testing
• Documentation
• Troubleshooting

---

Overview

The Citizen Reporting System enables citizens to report issues (road damage, health concerns, security issues, etc.) to government authorities while maintaining anonymity. The system features:

• Microservices Architecture: 11 independent services
• Event-Driven Communication: Apache Kafka for async messaging
• Strong Anonymity: Reporter identity protection
• RBAC + ABAC Authorization: Role and attribute-based access control
• Real-time Notifications: Multi-channel notification system
• SLA Management: Automatic escalation based on SLA policies
• Public Feed: Community engagement with upvoting

---

Architecture

Microservices

1. API Gateway - Single entry point, routing, rate limiting
2. Authentication Service - User authentication via Keycloak
3. Authorization Service - RBAC + ABAC enforcement
4. Report Service - Report management
5. Media Service - File upload handling (MinIO)
6. Case Management Service - Case lifecycle
7. Notification Service - Multi-channel notifications
8. Escalation Service - SLA monitoring and escalation
9. Feed Service - Public feed and search (OpenSearch)
10. Upvote Service - Community engagement
11. Integration Service - Event processing

Infrastructure

• PostgreSQL: Primary database (per-service isolation)
• Redis: Caching and session management
• Apache Kafka: Event streaming
• MinIO: S3-compatible object storage
• OpenSearch: Full-text search
• Keycloak: Identity and access management
• Prometheus + Grafana: Monitoring and metrics
• Jaeger: Distributed tracing

---

Tech Stack

Backend

• Language: Go 1.21+
• Framework: Gin
• Database: PostgreSQL 15
• Cache: Redis 7
• Message Broker: Apache Kafka 3.5
• Object Storage: MinIO
• Search Engine: OpenSearch 2.11

Frontend

• Framework: React 18
• Language: TypeScript
• Build Tool: Vite
• UI Library: Material-UI
• State Management: React Query
• Routing: React Router

DevOps

• Containerization: Docker
• Orchestration: docker-compose (local), Kubernetes (production)
• CI/CD: GitHub Actions
• Monitoring: Prometheus, Grafana, Jaeger

See TECHSTACK.md for complete details.

---

Prerequisites

Required Software

• Docker (>= 20.10)
• Docker Compose (>= 2.0)
• Make (for automation)

Optional (for local development)

• Go (>= 1.21)
• Node.js (>= 18)
• npm or yarn
• PostgreSQL Client (psql)

System Requirements

• RAM: Minimum 8GB (16GB recommended)
• Disk Space: 10GB free space
• OS: Linux, macOS, or Windows with WSL2

---

Quick Start

Option 1: Run Everything with Docker (Recommended for Testing)

# 1. Clone the repository
git clone <repository-url>
cd if4031-tubes-aat

# 2. Quick start (setup + infrastructure + services)
make quickstart

# Wait for infrastructure to be ready (~2 minutes)

# 3. Build and run all services
make build
make run

# 4. Check status
make status

# 5. Access the application
# Frontend: http://localhost:3000
# API Gateway: http://localhost:8081
# Keycloak Admin: http://localhost:8080 (admin/admin)

Option 2: Infrastructure Only (for Local Development)

# 1. Setup and start infrastructure
make setup
make infra-up

# 2. Wait for services to be healthy
make health

# 3. Run services locally (in separate terminals)
cd services/report-service
go run cmd/server/main.go

# 4. Run frontend
make dev-frontend

---

Detailed Setup

1. Initial Configuration

# Create environment file
make setup

# This creates .env from .env.example
# Edit .env to customize configuration

Default credentials:

• PostgreSQL: postgres/postgres
• Keycloak: admin/admin
• MinIO: minioadmin/minioadmin
• Grafana: admin/admin

2. Start Infrastructure Services

# Start all infrastructure (Kafka, PostgreSQL, Redis, etc.)
make infra-up

# Verify infrastructure is running
docker ps

# Check health
make health

Access URLs:

• PostgreSQL: localhost:5432
• Redis: localhost:6379
• Kafka: localhost:29092 (external) / kafka:9092 (internal)
• Kafka UI: http://localhost:8090
• MinIO Console: http://localhost:9001
• OpenSearch: http://localhost:9200
• Keycloak: http://localhost:8080
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3001
• Jaeger: http://localhost:16686

3. Create Kafka Topics

# Create required Kafka topics
make kafka-create-topics

# List topics
make kafka-topics

4. Database Setup

Databases are created automatically on PostgreSQL startup via init-db.sql.

Databases created:

• auth_db
• authz_db
• report_db
• media_db
• case_db
• notification_db
• escalation_db
• upvote_db
• feed_db
• integration_db
• keycloak

5. Build Services

# Build all Docker images
make build

# This may take 5-10 minutes on first run

---

Running the Application

Full Stack (Docker Compose)

# Start everything
make run

# View logs
make logs

# View logs for specific service
make logs-service SERVICE=report-service

# Check status
make status

# Stop everything
make stop

# Restart
make restart

Individual Services

# Start only microservices (infrastructure must be running)
make services-up

# Stop only microservices
make services-down

Accessing Services

Service	Port	URL
Frontend	3000	http://localhost:3000
API Gateway	8081	http://localhost:8081
Auth Service	8082	http://localhost:8082
Authorization Service	8083	http://localhost:8083
Report Service	8084	http://localhost:8084
Media Service	8085	http://localhost:8085
Case Service	8086	http://localhost:8086
Notification Service	8087	http://localhost:8087
Escalation Service	8088	http://localhost:8088
Feed Service	8089	http://localhost:8089
Upvote Service	8091	http://localhost:8091
Integration Service	8092	http://localhost:8092

---

Development

Backend Development (Go)

# 1. Start infrastructure only
make infra-up

# 2. Navigate to service
cd services/report-service

# 3. Install dependencies
go mod download

# 4. Run service
go run cmd/server/main.go

# 5. Run tests
go test ./...

# 6. Run tests with coverage
go test -cover ./...

Frontend Development (React)

# 1. Navigate to frontend
cd frontend

# 2. Install dependencies
npm install

# 3. Start development server
npm run dev

# 4. Build for production
npm run build

# 5. Preview production build
npm run preview

# Frontend will be available at http://localhost:3000

Hot Reload

For Go services, use tools like:

• air: go install github.com/cosmtrek/air@latest
• CompileDaemon: go get github.com/githubnemo/CompileDaemon

# Example with air
cd services/report-service
air

---

Testing

Unit Tests

# Run all unit tests
make test-unit

# Test specific service
cd services/report-service
go test ./internal/domain/service/... -v

Integration Tests

# Run integration tests
make test-integration

# Integration tests use Testcontainers for real dependencies

End-to-End Tests

# Run E2E tests (requires all services running)
cd tests/e2e/cypress
npm install
npx cypress open

---

Documentation

• TECHSTACK.md - Complete technology stack
• DB_SCHEMA.md - Database schema documentation
• STRUCTURE.md - Project structure and folder organization
• CLAUDE.md - System requirements and architecture guidelines

API Documentation

API documentation is available via Swagger/OpenAPI:

• After starting services, visit: http://localhost:8081/swagger/index.html

---

Troubleshooting

Common Issues

1. Port Conflicts

# Check what's using a port
lsof -i :8080

# Stop conflicting services or change ports in docker-compose.yml

2. Out of Memory

# Increase Docker memory allocation
# Docker Desktop > Settings > Resources > Memory (set to 8GB+)

3. Containers Not Starting

# Check logs
make logs

# Restart specific service
docker-compose restart report-service

# Clean restart
make clean
make run

4. Database Connection Issues

# Check PostgreSQL is running
make health

# Connect to database
make db-psql

# Check database exists
\l

5. Kafka Issues

# Check Kafka is running
docker logs citizen-reporting-kafka

# List topics
make kafka-topics

# Recreate topics
make kafka-create-topics

# Access Kafka UI
# http://localhost:8090

Cleanup

# Stop and remove containers
make stop

# Remove containers and volumes
make clean

# Remove everything including images
make clean-all

# Start fresh
make setup
make infra-up
make build
make run

Logs and Debugging

# View all logs
make logs

# View specific service
make logs-service SERVICE=report-service

# Follow logs in real-time
docker-compose logs -f report-service

# Check service health
make health

---

Makefile Commands Reference

make help              # Show all available commands
make setup             # Initial setup
make infra-up          # Start infrastructure only
make infra-down        # Stop infrastructure
make build             # Build all services
make run               # Run all services
make stop              # Stop all services
make logs              # View all logs
make status            # Show service status
make health            # Check health of services
make clean             # Clean up containers and volumes
make quickstart        # Quick start (setup + infra)
make all               # Setup, build, and run everything

---

Project Status

This is currently a skeleton project with:

• ✅ Complete folder structure
• ✅ Docker configuration
• ✅ docker-compose setup
• ✅ Infrastructure services configured
• ✅ Makefile automation
• ⏳ Service implementations (TODO)
• ⏳ Frontend implementation (TODO)
• ⏳ Tests (TODO)

Next Steps

1. Implement Report Service
2. Implement Authentication & Authorization
3. Implement Case Management
4. Set up event-driven flows
5. Implement remaining services
6. Build frontend components
7. Write tests
8. Deploy to Kubernetes

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

This project is part of an academic assignment for IF4031 - Advanced Application Technology course.

---

Support

For issues and questions:

• Create an issue in the repository
• Contact the development team

---

Happy Coding! 🚀