CivicLens

A civic engagement platform that empowers the general public to report local issues (road damage, mosquito breeding sites, garbage collection failures, etc.) and routes those reports to the responsible institutions via an AI-powered classification system.

---

Monorepo Structure

CivicLens/
├── backend-api/        # Go REST API (Echo + sqlc + pgx)
├── frontend/           # Next.js admin dashboard
├── mobile-app/         # Retired mobile client (kept for project history)
├── agentic-system/     # Python / LangGraph AI classification pipeline
├── docker-compose.yml  # Local development stack
├── lefthook.yml        # Git hook orchestration
├── commitlint.config.js# Commit message rules
└── package.json        # Root-level Node devDependencies

---

Prerequisites

Tool	Version	Purpose
Go	≥ 1.25	Backend API
Node.js	≥ 20	Frontend and root tooling
Docker + Compose	latest	Local database & services
Python	≥ 3.11	Agentic system

---

Quick Start

1 — Clone and install root tooling

git clone https://github.com/specfor/civiclens.git
cd civiclens
npm install        # installs commitlint + lefthook and runs `lefthook install`

The npm install automatically runs lefthook install via the prepare script, which wires up the git hooks.

2 — Start the local development stack

# Build and start PostgreSQL, API, admin dashboard, pgAdmin, and Qdrant
docker compose up -d --build

# Or use the separate dev environment:
docker compose -f docker-compose.dev.yml up -d

Admin dashboard: Open http://localhost:3000/login and sign in with admin@civiclens.org / AdminPass123!.

Database UI: pgAdmin is available at http://localhost:5050 with email admin@civiclens.com and password admin. Its master password protects only saved pgAdmin connections on your own installation.

Tip: To develop the API with hot-reload, stop the api container and run make run inside backend-api/ instead.

3 — See per-project READMEs

• Backend API
• Frontend
• Retired Mobile App
• Agentic System

---

Commit Message Conventions

Every commit must follow the Conventional Commits specification. This is enforced automatically by commitlint + lefthook on every git commit.

Format

type(scope): subject

[optional body]

[optional footer(s)]

Types

Type	When to use
feat	A new user-facing feature
fix	A bug fix
docs	Documentation changes only
style	Whitespace / formatting — no logic change
refactor	Code restructure without feature change or bug fix
perf	Performance improvement
test	Adding or correcting tests
chore	Maintenance — deps, build scripts, tooling
ci	CI/CD pipeline changes
revert	Reverts a previous commit
build	Build system / compilation changes

Scopes

Scopes are optional but must come from the approved list if used:

Scope	Area
repo	Root-level / monorepo-wide changes
docker	Docker / Compose files
api	General backend API
auth	Authentication & authorisation
db	Database layer (migrations, sqlc)
reports	Issue reports feature
categories	Report categories
institutions	Institution management
users	User management
frontend	Admin frontend (Next.js)
admin	Admin portal pages
mobile	Mobile app (React Native)
agent	AI/LLM agentic system
classifier	Report classification pipeline

Rules

• Subject must be imperative mood, no trailing period (uppercase letters allowed for proper nouns)
• Subject length: 10–100 characters
• Body (if present): must be separated from subject by a blank line; max 100 chars per line
• Footer (if present): must be separated from body by a blank line

Valid Examples

feat(api): add health check endpoint
fix(db): correct migration rollback on constraint violation
docs(repo): add commit message conventions to readme
chore(docker): upgrade postgres image to 16-alpine
test(auth): add jwt validation unit tests
refactor(reports): extract image upload logic into service layer
feat(mobile): implement gps location capture on report submission

Invalid Examples

# ❌ Missing type
add new endpoint

# ❌ Unknown type
update(api): fix stuff

# ❌ Subject too short
fix(db): fix

# ❌ Subject starts with uppercase
feat(api): Add health endpoint

# ❌ Trailing period
feat(api): add health endpoint.

Breaking Changes

Append ! after the type/scope or add BREAKING CHANGE: in the footer:

feat(api)!: remove v1 legacy endpoints

BREAKING CHANGE: /api/v1/old-path has been removed. Use /api/v2/new-path instead.

---

Pre-Commit Hooks (Lefthook)

When you stage files and run git commit, lefthook automatically runs:

Hook	Trigger	What runs
go-format	.go files in backend-api/	gofmt + goimports
frontend-lint	JS/TS/CSS in frontend/	eslint --fix + prettier --write
mobile-lint	JS/TS in mobile-app/	eslint --fix + prettier --write
python-format	.py in agentic-system/	ruff check --fix + ruff format
commitlint	every commit message	Validates against Conventional Commits

All pre-commit hooks run in parallel. Only files relevant to your changes are processed (staged files only).

Skipping hooks (emergency use only)

git commit --no-verify -m "chore(repo): emergency hotfix"

⚠️ Only use --no-verify in genuine emergencies. CI will still enforce the same rules.

---

Code Style Summary

Language	Formatter	Linter
Go	gofmt + goimports	golangci-lint
TypeScript/JS	prettier	eslint
Python	ruff format	ruff check

---

Contributing

We welcome contributions to CivicLens! To ensure stability and code quality, please follow our strict contribution guidelines below.

🌿 Branching Strategy

• dev: The stable development branch. All feature branches and pull requests must target dev.
• main: The production branch. Code is merged from dev to main only when it is stable and ready for release.
• Direct Commits: NO direct commits are allowed to the main or dev branches. You must always create a feature branch and open a Pull Request (PR).

🛠️ Pull Request Process

1. Create a feature branch off dev: git checkout -b feat/your-feature.
2. Make your changes and commit them following the Conventional Commits guidelines.
3. Open a Pull Request targeting the dev branch.
4. Code Review: Every Pull Request requires at least one person reviewing and accepting the changes before it can be merged.

🧪 Test-First Development

We employ a test-first development strategy.

• Tests are Mandatory: Everybody must ensure that tests are up to date with the changes they are making.
• Run Tests Locally: You should try running all related unit and E2E tests locally before opening a pull request to ensure nothing is broken.

📝 Good Coding Practices

• Commenting: Add a fair amount of comments, but only in required places. Do not bloat the codebase with obvious or redundant comments. Explain the "why", not the "what".

🤖 Usage of AI Agents

You are welcome to use AI agents (like Copilot, Cursor, or LangGraph) to assist with coding. However, everything must be manually reviewed by you, the developer, before committing the code or opening a pull request. Do not blindly trust AI-generated code.

---

License

MIT — see LICENSE.