conveniat27 - Official Website

This repository contains the source code for the official website as well as the official app of conveniat27, built with Next.js and Payload CMS.

Table of Contents

• Core Technologies
• Prerequisites
• Getting Started
• Project Structure
• Key Concepts
• Database Maintenance
• SSH Tunneling / Troubleshooting
• License

Core Technologies

• Framework: Next.js (App Router)
• TRPC: tRPC (for type-safe API routes)
• CMS: Payload CMS (Headless, Self-hosted)
• Language: TypeScript (with strict type checking)
• UI: React, shadcn/ui, Tailwind CSS, Headless UI
• Icons: Lucide React
• Database: MongoDB (self-hosted), MinIO (S3-compatible object storage, self-hosted), PostgreSQL (self-hosted)
• PWA: Serwist (for Service Worker management)
• Code Quality: ESLint, Prettier
• Development Environment: Docker (Devcontainer)

Prerequisites

Ensure you have the following installed on your system:

• Git
• Docker & Docker Compose
• An IDE that supports Devcontainers (e.g., VS Code with the Dev Containers extension, WebStorm).

Getting Started

Launch Project Locally (Devcontainer Recommended)

1. Clone the repository
2. Copy the .env.example file to .env and fill empty values.
3. Open the project using the provided devconatiner inside your IDE (VSCode or Webstorm are tested).
4. Start Developing using the following commands:

   docker compose up --build

   The above command launches a local development server with hot-reloading enabled. You can open the website on http://localhost:3000.

Local Development Commands

• Install Dependencies: pnpm install
• Start Development Server: docker compose up --build (this uses the default dev profile defined in .env)
• Stop Development Server: docker compose down
• Clear Database & Volumes: To completely reset the database and remove Docker volumes (useful for reseeding):

  docker compose down --volumes

  After running this, you'll need to restart the server with docker compose up --build to re-initialize and potentially re-seed the database based on Payload's configuration.

Observability Stack

The project includes an optional observability stack (Prometheus, Grafana, Loki, Tempo). To start the project with these tools enabled locally:

docker compose --profile observability up --build

Accessing the Payload Admin Panel

Once the development server is running, you can typically access the Payload CMS admin interface at: http://localhost:3000/admin (or your configured admin route)

Project Structure

The project structure is influenced by Next.js App Router conventions and principles from Bulletproof React, emphasizing modularity and maintainability.

Folder Overview

public/         # Static assets (images, fonts, etc.)
src/
|
+-- app/              # Next.js App Router: Layouts, Pages, Route Handlers
|   |-- (entrypoint)/ # Entrypoint for the APP (manually localized)
|   |-- (payload)/    # Routes related to Payload Admin UI
|   |-- (frontend)/   # Routes for the main website frontend / app
|
+-- components/       # Globally shared React components
|
+-- config/           # Global application configurations (e.g., exported env vars)
|
+-- features/         # Feature-based modules (self-contained units of functionality)
|   |-- service-worker/ # Serwist service worker logic
|   |-- payload-cms/    # Payload CMS specific configurations, collections, globals, hooks
|   +-- ...             # Other features
|
+-- hooks/            # Globally shared React hooks
|
+-- lib/              # Globally shared utility functions, libraries, clients
|
+-- types/            # Globally shared TypeScript types and interfaces
|
+-- utils/            # Globally shared low-level utility functions

Feature-Based Modularity

• Most application logic resides within the src/features directory.
• Each sub-directory in src/features represents a distinct feature (e.g., chat, map, payload-cms).
• Encapsulation: Code within a feature folder should primarily relate to that specific feature.
• Structure within Features: A feature can internally have its own components, hooks, api, types, utils subdirectories, scoped to that feature.
• Import Restrictions: ESLint rules (import/no-restricted-paths in eslint.config.mjs) enforce unidirectional dependencies:
  • app can import from features and shared directories (components, hooks, etc.).
  • features cannot import from app or shared directories.
  • Features generally should not import directly from other features, promoting loose coupling. Exceptions are explicitly defined (e.g., payload-cms and next-auth can be imported more broadly).
  • Shared directories (components, hooks, lib, types, utils) should not import from app or features.
• Payload CMS Exception: The payload-cms feature is central and can be imported by other parts of the application as it defines the core data structures / content types used throughout the app.

This structure aids scalability, maintainability, and team collaboration by keeping concerns separated.

Key Concepts

Page Rendering

A core aspect of this project is that most frontend pages are generated based on data managed within Payload CMS.

1. CMS Configuration (src/features/payload-cms/payload.config.ts, src/features/payload-cms/settings): Defines data structures (Collections, Globals) and their fields. Collections might represent page types, blog posts, etc.
2. Routing (src/app/(frontend)/[locale]/(payload-pages)/[...slugs]/page.tsx): This dynamic route catches most frontend URL paths.
3. Route Resolution: The application resolves the incoming URL (slugs) against Collections and Globals defined in Payload CMS (via the src/features/payload-cms/routeResolutionTable.ts).
4. Layout & Component Mapping: Once the corresponding CMS data is found for a URL, a specific page layout ( src/features/payload-cms/page-layouts) is rendered. Complex CMS fields (like Blocks or Rich Text) are mapped to React components using converters (src/features/payload-cms/converters).

To improve performance, calls to Payload CMS are cached server-side using Next.js 'use cache' functionality.

Caching in Development

In development mode (NODE_ENV=development), the custom cache handler (Redis/FileSystem) is disabled. Next.js uses its default in-memory cache in development.

Progressive Web App (PWA)

This application utilizes Serwist (@serwist/next) to implement Service Worker functionality, enabling PWA features:

• Offline Access: Pre-cached pages (like the /~offline page) and potentially other assets allow basic functionality when the user is offline.
• Caching: Improves performance by caching assets and network requests.
• Reliability: Provides a more resilient user experience on flaky networks.

Service Worker in Development

By default, the Service Worker is disabled during local development (docker compose up) to prevent caching issues with Hot Module Replacement (HMR).

To enable the Service Worker locally and simulate a production-like environment (including file watching and rebuilding), use the service-worker profile:

docker compose --profile service-worker up --watch --build

This uses docker watch to sync file changes and trigger rebuilds, leveraging the Turbopack file system cache for faster subsequent builds.

Code Quality & Conventions

Maintaining code quality and consistency is crucial.

TypeScript Strictness

The project enforces strict TypeScript settings (tsconfig.json), including: strict, strictNullChecks, noImplicitAny, noUncheckedIndexedAccess, exactOptionalPropertyTypes, etc. This helps catch errors at compile time and improves code reliability.

Linting and Formatting

• ESLint (eslint.config.mjs): Used for identifying and reporting on patterns in JavaScript/TypeScript code. Includes rules from eslint:recommended, typescript-eslint, unicorn, react-hooks, next/core-web-vitals, and custom rules for conventions and import restrictions.
• Prettier: Used for automatic code formatting to ensure a consistent style. Integrated via eslint-plugin-prettier.
• Run Checks: (Ensure these scripts exist in your package.json)

  # Run ESLint checks and fix issues
  pnpm run lint

Import Restrictions

As mentioned in the Project Structure section, ESLint rules strictly enforce module boundaries to maintain a clean and understandable architecture. Path aliases (@/*, @payload-config) defined in tsconfig.json are used for cleaner imports.

UI Component Library

• shadcn/ui: Provides beautifully designed, accessible components built on Radix UI and Tailwind CSS. Components are typically copied into the project (src/components/ui) rather than installed as a dependency.
• Headless UI: Used for unstyled, accessible UI components providing underlying logic for elements like modals, dropdowns, etc.
• Lucide React: Provides a wide range of clean and consistent SVG icons.

Environment Variables

• Configuration is managed via environment variables.
• .env.example serves as a template listing the required variables.
• Create a .env file (copied from .env.example) for local development. Never commit .env files to Git.
• Populate .env with necessary credentials (database URLs, API keys, secrets, etc.).

Build Production Bundle

The easiest way to build the page into a production ready bundle is to use the provided Docker Compose file. This will build the Next.js application and Payload CMS, and prepare it for deployment.

docker compose -f docker-compose.prod.yml up --build

However, you can also build the application manually using the following commands. Please ensure that you have deleted node_modules, src/lib/prisma/*, and .next before running the commands to ensure a clean build.

Also make sure that you DON'T have any .env file in the root of the project, as this will cause issues with the build process.

# Export environment variables
export $(grep -v '^#' .env | grep '^NEXT_PUBLIC_' | xargs)
export BUILD_TARGET="production"
export NODE_ENV="production"
export DISABLE_SERVICE_WORKER="true" # speeds up build process (optional)
export PRISMA_OUTPUT="src/lib/prisma/client/"

# Install dependencies
pnpm install

# Create build info file
bash create_build_info.sh

# Generate Prisma client
npx prisma generate --no-hints

# Build the Next.js application
pnpm next build

Analyse Bundle Size

To analyze the bundle size of the Next.js application, you can use the next-bundle-analyzer package. Xou can run the following command to analyze the bundle size. This will generate a report and open it in your default browser.

ANALYZE=true pnpm build

Git Workflow

We follow a standard Git workflow for managing changes:

1. Branching: Create a new branch for each (bigger) feature or bug fix.
   • Use descriptive names (e.g., feature/new-header, bugfix/fix-footer).
   • For small changes, you can commit directly to the dev branch.
   • For larger features, create a feature branch from dev and merge it back when complete.
   • You are allowed to force push to your feature branches. However, if multiple developers are collaborating on the same feature branch, always coordinate and communicate with your teammates before force pushing, as it can overwrite others' work. Avoid force pushing to dev, and never force push to main.
2. Pull Requests: When ready, open a pull request (PR) against the dev branch.
   • Ensure the PR description is clear about the changes made.
   • Request reviews from team members.
   • Once approved, we merge the PR into dev.
3. Releases: When ready to deploy, merge dev into main.
   • We do not use squash merging for releases, instead, we use regular merging to preserve commit history.
   • After every release, we rebase the dev branch from main to keep it up to date without introducing merge commits.
   • We may squash merge features into dev to keep the history clean.
4. Hotfixes: For urgent fixes, create a hotfix branch from main, apply the fix, and merge it back into both main and dev. Hotfix branches should be named like hotfix/fix-issue.

Migrate Production Database

The following commands are used to generate and apply migrations to the postgreSQL database. Here you can find an in-depth guide on how to use Prisma Migrate.

###############################################
# Generate and apply migrations to remote databases
###############################################
# 1. Establish SSH Tunnel (separate terminal)
pnpm db:tunnel-dev # or pnpm db:tunnel-prod

# 2. Set password (for the remote database)
export DB_PASSWORD=

# 3. Connect via the tunnel on localhost:5433
# (Note: 5433 is used for the tunnel, 5432 is for your local instance)
export CHAT_DATABASE_URL="postgres://conveniat27:$DB_PASSWORD@localhost:5433/conveniat27"

# for konekta
pnpm db:tunnel-konekta
export DB_PASSWORD=
export CHAT_DATABASE_URL="postgres://konekta:$DB_PASSWORD@localhost:5433/konekta"

# Check status
npx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma

# Create/Apply migrations
npx prisma migrate dev --schema prisma/schema.prisma # for dev
npx prisma migrate deploy --schema prisma/schema.prisma # for prod

Database Maintenance

If you see warnings about collation version mismatch (e.g., The database was created using collation version 2.36, but the operating system provides version 2.41), you need to update the collation version to match the current OS.

Run the following SQL command against the database:

ALTER
DATABASE conveniat27 REFRESH COLLATION VERSION;

SSH into the server and run the following command to execute the SQL command:

Production (conveniat.ch)

If asked for a password for the user conveniat27, use the production database password.

docker run --rm -it --network conveniat_backend-net postgres:17 \
  psql -h conveniat_postgres -U conveniat27 -d conveniat27 -c "ALTER DATABASE conveniat27 REFRESH COLLATION VERSION;"

Development (conveniat27.cevi.tools)

If asked for a password for the user conveniat27, use the development database password.

docker run --rm -it --network conveniat-dev_backend-net postgres:17 \
  psql -h conveniat-dev_postgres -U conveniat27 -d conveniat27 -c "ALTER DATABASE conveniat27 REFRESH COLLATION VERSION;"

Interactive SQL Console

To open an interactive psql shell (instead of running a single command), simply omit the -c argument:

Production:

docker run --rm -it --network conveniat_backend-net postgres:17 \
  psql -h conveniat_postgres -U conveniat27 -d conveniat27

Development:

docker run --rm -it --network conveniat-dev_backend-net postgres:17 \
  psql -h conveniat-dev_postgres -U conveniat27 -d conveniat27

Connect from Localhost

To directly connect to the database from your local machine, use the provided script to open an SSH Tunnel. This tunnel supports both Postgres (local 5433) and MongoDB (local 27018).

Open Tunnel:

The tunnel runs in the foreground and forwards traffic to the remote infrastructure.

pnpm db:tunnel-prod  # For Production
pnpm db:tunnel-dev   # For Development

Synchronize Database

You can easily sync the entire database state (Postgres + MongoDB) between your local environment and the remote servers.

Pull (Remote -> Local)

Copies the state from the remote database to your local Docker instance.

1. Open a tunnel (see above).
2. Run the pull command:

   pnpm db:pull

3. Follow the prompts for the remote database passwords.

Push (Local -> Remote DEV)

Updates the remote Development state with your local data. Safety confirmation required.

1. Open the dev tunnel: pnpm db:tunnel-dev.
2. Run the push command:

   pnpm db:push-dev

SSH Tunneling / Troubleshooting

If you encounter errors when opening a tunnel, follow these steps:

"Bind for 127.0.0.1:5433 failed: port is already allocated"

This usually happens because a previous tunnel container is still running on the remote host. The updated commands above automatically attempt to stop the existing container (db-tunnel-prod or db-tunnel-dev) before starting a new one.

Manual Cleanup

If the automatic stopping fails, SSH into the host and run:

docker rm -f db-tunnel-prod  # or db-tunnel-dev

Signal Propagation

The scripts use the -t flag in SSH and --init flag in Docker to ensure that when you press Ctrl+C on your local machine, the signal is propagated correctly to the remote container, allowing it to exit and clean itself up (via --rm).

How this works:

• The tunnel script starts a forwarder container on the manager node.
• It maps local ports (5433 for PG, 27018 for Mongo) to the manager, which in turn forwards to the internal network.
• The sync scripts use pg_dump/psql and mongodump/mongorestore to stream data over these ports.
• Your local machine tunnels to the manager's mapped ports.

License

This project is licensed under the MIT License — see the LICENSE file for details.