CommonGround is a discussion platform that aims to facilitate concensus through rationale discussions. Users can post viewpoints, reference sources, and engage with opposing perspectives in a structured way, backed by a recommendation system designed to surface dialogue across, rather than within, ideological bubbles.
The platform was supported by NYCU Software Development Club.
The CommonGround stack is split across the following repositories:
| Repository | Description | Stack |
|---|---|---|
frontend |
The web application served at commonground.tw. | Next.js, pnpm, Playwright |
backend |
The primary application server handling users, posts, viewpoints, and authentication. | Java, Spring Boot, Gradle |
api |
The OpenAPI specification and Swagger documentation shared between the frontend and backend. | OpenAPI 3, Swagger UI |
recommendation-system |
A recommendation worker that ranks viewpoints per user and writes results into a Redis ZSET. The backend reads recommendations from the same Redis instance — the two services do not call each other directly. | Python, Redis, OpenAI |
reference-system |
An offline LLM job that reads issues and viewpoints from the backend's HTTP API, generates RAG / few-shot summaries with citations, and PUTs the results back to the backend. |
Python, LangChain |
Each service ships with its own Dockerfile, and the application is designed to run as a small set of containers behind the frontend.
- Docker and Docker Compose
- A Redis instance (used by
recommendation-system) - A PostgreSQL instance (used by
backend) - Google OAuth2 credentials (used by
backendfor sign-in) - An OpenAI API key (used by
recommendation-systemfor embeddings)
-
Clone the repositories you intend to run. At minimum you will need
frontend,backend,recommendation-system, andreference-system.git clone https://github.com/commonground-project/frontend.git git clone https://github.com/commonground-project/backend.git git clone https://github.com/commonground-project/recommendation-system.git git clone https://github.com/commonground-project/reference-system.git
-
Configure each service. Every repository contains a README describing the environment variables it expects. The key items are:
backend: copyapplication.propertiesintoapplication-dev.propertiesand fill in your Google OAuth2 client ID and secret.recommendation-system: setBASE_URL,BEARER_API_TOKEN,OPENAI_API_KEY, and Redis connection variables. This worker shares its Redis instance with the backend — both must point at the same Redis.reference-system: configure its.envwith credentials for the backend's HTTP API (it reads from andPUTs back to the deployed backend) and an OpenAI / LLM key for summarization.frontend: copyexample.envto.envand point it at your backend.
-
Build the images. Run
docker buildin each service's repository root to produce a local image. -
Run the stack. Start Redis and PostgreSQL, then bring up
backendand thefrontend.recommendation-systemruns as a worker against the shared Redis;reference-systemruns as a batch job against the backend's HTTP API. Neither is on the request path, so the site is usable without them, you just won't get personalized rankings or AI-generated reference summaries. -
Verify the deployment by visiting the frontend in a browser and signing in via Google OAuth.
For per-service configuration details, refer to the README of each repository linked above.
This project is archived. CommonGround is no longer actively maintained, and the repositories under this organization are preserved for reference and for anyone who wishes to fork, study, or build on the work.
Future authors interested in reviving the project, taking ownership of the domain, or asking about the codebase are welcome to get in touch at contact@commonground.tw.
