TransparentProcure Kenya 🇰🇪

A public procurement oversight platform built for transparency and accountability in Kenyan county-level government contracting.

TransparentProcure enables citizens, auditors, and oversight officers to monitor tenders, track contractor compliance, flag fraud alerts, and crowdsource ward-level project updates — all backed by real-time data from a MySQL database.

1. Project Overview
2. Tech Stack
3. Project Structure
4. Prerequisites
5. Database Setup (MySQL via XAMPP/LAMPP)
6. Backend Setup (Spring Boot)
7. Frontend Setup (React + Vite)
8. Environment Variables Reference
9. Running the Full System
10. API Endpoints Reference
11. Default Data
12. Troubleshooting

transparent_java/
├── springboot-backend/                  # Spring Boot API
│   ├── src/main/java/com/transparentprocure/
│   │   ├── config/                      # Security configuration
│   │   ├── controller/                  # REST controllers (Auth, Dashboard, Feed, Registry, Fraud, Audit, Reports, Tenders)
│   │   ├── dto/                         # Request/response DTOs
│   │   │   └── request/                 # Incoming request bodies
│   │   ├── entity/                      # JPA entities (mapped to MySQL tables)
│   │   ├── model/                       # User model
│   │   ├── repository/                  # Spring Data JPA repositories
│   │   ├── security/                    # JWT filter, token utility, user details service
│   │   └── service/                     # Business logic & database-backed data service
│   ├── src/main/resources/
│   │   ├── application.properties       # App configuration (no secrets — uses .env)
│   │   └── data/                        # Seed JSON files (mock_data.json, posts.json, tender.json)
│   ├── .env.example                     # ← Copy this to .env and fill in your credentials
│   ├── .env                             # ← Your local credentials (gitignored — never committed)
│   └── pom.xml                          # Maven dependencies
│
└── frontend/                            # React + Vite SPA
    ├── src/
    │   ├── api/apiService.js            # Axios client + all API endpoint definitions
    │   ├── context/AuthContext.jsx      # Global authentication state (JWT + localStorage)
    │   ├── components/                  # Layout, Sidebar, Topbar, ProtectedRoute
    │   ├── hooks/useApi.js              # Generic data-fetching hook
    │   └── pages/                       # Login, Dashboard, Feed, Registry, Fraud, Audit, Reports
    ├── .env                             # Frontend env (VITE_API_BASE_URL — safe to track)
    ├── vite.config.js                   # Dev server + proxy to Spring Boot
    └── package.json

Make sure the following are installed on your machine before starting:

Verify your installations:

java -version        # should print: openjdk 21...
mvn -version         # should print: Apache Maven 3.x...
node -version        # should print: v18.x or v20.x or higher
npm -version         # should print: 9.x or higher

The backend uses MySQL 8 managed through XAMPP / LAMPP. Follow these steps exactly.

On Linux (LAMPP):

sudo /opt/lampp/lampp start

On Windows (XAMPP): Open the XAMPP Control Panel and click Start next to MySQL.

On macOS (XAMPP): Open the XAMPP application and click Start next to MySQL.

Confirm MySQL is running:

# Linux
sudo /opt/lampp/bin/mysql -u root -p

# Windows / macOS — use phpMyAdmin or the XAMPP shell

XAMPP ships with MySQL root having no password by default.
You must set a password before using this application.

-- Inside the MySQL shell:
ALTER USER 'root'@'localhost' IDENTIFIED BY 'YourChosenPassword';
FLUSH PRIVILEGES;
EXIT;

Note down the password you set — you will need it in the next step.

You do not need to run any SQL scripts.
The Spring Boot application creates the transparent_procure database and all tables on first startup via the JPA ddl-auto=update setting.

It also seeds all initial data (contractors, tenders, fraud alerts, audits, reports, wards, counties, feed posts) automatically from the JSON files in src/main/resources/data/.

git clone https://github.com/YOUR_USERNAME/transparent_java.git
cd transparent_java

The backend reads sensitive configuration (database password, JWT secret) from a .env file that is never committed to git.

cd springboot-backend
cp .env.example .env

Open .env in any text editor and fill in your values:

# Database
DB_URL=jdbc:mysql://localhost:3306/transparent_procure?createDatabaseIfNotExist=true&useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
DB_USERNAME=root
DB_PASSWORD=YourMySQLPasswordHere          # <-- the password you set in Step 2 above

# JWT Secret — must be at least 64 characters
# Generate one with:  openssl rand -hex 64
JWT_SECRET=replace_this_with_a_long_random_secret_string_of_at_least_64_characters
JWT_EXPIRATION=86400000

# Server
SERVER_PORT=3001

# App
APP_MOCK_TOKEN=mock_jwt_token_for_development_purpose_only

JWT_SECRET rules:

• Must be at least 64 characters (required by the HS512 signing algorithm).
• All developers working on the same running instance must use the same secret (tokens are only valid on the server that signed them).
• Each developer working independently can use their own secret.
• Generate a strong one with: openssl rand -hex 64

# Still inside springboot-backend/
mvn clean package -DskipTests

A successful build prints:

[INFO] BUILD SUCCESS

Option A — Maven (recommended for development):

# Run from inside springboot-backend/
mvn spring-boot:run

Option B — JAR directly (recommended for keeping it running in background):

# Run from inside springboot-backend/
nohup java -jar target/transparent-procure-api-2.0.0.jar > /tmp/api.log 2>&1 &
echo "Started PID: $!"

# Watch the log:
tail -f /tmp/api.log

The server is ready when you see:

Started TransparentProcureApplication in X.XXX seconds

Verify it is running:

curl http://localhost:3001/api/health
# Expected: {"success":true,"data":{"status":"healthy"},...}

Important: Always run the backend from inside the springboot-backend/ directory so that Spring Boot finds the .env file in the current working directory.

# If you know the PID:
kill <PID>

# Find and kill by port:
kill $(lsof -ti :3001)       # Linux / macOS

# From the project root
cd frontend
npm install

The frontend/.env file is already configured and tracked in git. It contains only a non-secret URL:

VITE_API_BASE_URL=http://localhost:3001/api

No changes are needed unless your backend runs on a different port.

# From inside frontend/
npm run dev

The terminal will print something like:

  VITE v7.x.x  ready in 300ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose

Open http://localhost:5173 in your browser.

The Vite dev server automatically proxies all /api/* requests to http://localhost:3001 (the Spring Boot backend). Both servers must be running at the same time.

npm run build
# Output goes to frontend/dist/

Variables without a default will cause the application to fail to start if not provided. Always copy .env.example to .env and fill in all values.

In development (npm run dev), the Vite proxy handles all /api requests automatically — VITE_API_BASE_URL is not used.

Open two terminal tabs and run each command in its own tab:

Terminal 1 — Backend:

cd transparent_java/springboot-backend
mvn spring-boot:run

Terminal 2 — Frontend:

cd transparent_java/frontend
npm run dev

Then open http://localhost:5173 in your browser.

All endpoints are prefixed with /api. The backend runs on http://localhost:3001.

On first startup, the backend automatically seeds the database with realistic mock data:

Data seeding only runs when the tables are empty. Restarting the server does not duplicate data.

Another instance of the backend is already running. Find and kill it:

# Linux / macOS
kill $(lsof -ti :3001)

# Windows (PowerShell)
netstat -ano | findstr :3001
taskkill /PID <PID_NUMBER> /F

Your DB_PASSWORD in springboot-backend/.env does not match your MySQL root password.

1. Verify your MySQL password works:

   /opt/lampp/bin/mysql -u root -p
   # Enter your password when prompted

2. Update DB_PASSWORD in springboot-backend/.env to match.
3. Restart the backend.

You have not created the .env file. Run:

cd springboot-backend
cp .env.example .env
# Then edit .env and fill in DB_PASSWORD and JWT_SECRET

Your JWT_SECRET in .env is shorter than 64 characters. Generate a valid one:

openssl rand -hex 64

Paste the output as the value of JWT_SECRET in .env.

The Vite dev server proxy is not reaching the backend. Check:

1. The backend is running on port 3001: curl http://localhost:3001/api/health
2. You are running the frontend with npm run dev (not a static build).
3. frontend/vite.config.js has the proxy pointing to http://localhost:3001.

cd frontend
npm install     # re-install dependencies
npm run dev

This is a warning, not an error. The application still starts and runs correctly. You can silence it by removing the spring.jpa.properties.hibernate.dialect line from application.properties.

# Check if another MySQL is already running on port 3306
lsof -i :3306

# Stop the conflicting process, then restart LAMPP
sudo /opt/lampp/lampp restart

• Never commit .env — it is in .gitignore. If you accidentally do, revoke and rotate your credentials immediately.
• The .env.example file is safe to commit — it contains only placeholder values.
• Each developer generates their own JWT_SECRET locally. As long as you work independently, this is fine.
• The DB_PASSWORD in .env is only your local development MySQL password — it has no access to any production system.
• frontend/.env contains only http://localhost:3001/api — no secrets, safe to commit.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -m "feat: describe your change"
4. Push to the branch: git push origin feature/your-feature-name
5. Open a Pull Request

This project is developed for the Public Procurement Regulatory Authority of Kenya oversight initiative.

© 2024 TransparentProcure Kenya. All rights reserved.