FountainCMS Monorepo

FountainCMS is a headless, data-first Content Management System designed to manage structured content, datasets, and metadata in a clean, scalable, and developer-friendly way.

This repository is organized as a monorepo containing both the frontend (React) and backend (NestJS) codebases that together power the FountainCMS ecosystem.

---

🚀 What is FountainCMS?

FountainCMS focuses on explicit content modeling and API-first delivery.

Instead of tightly coupling content with presentation, it treats content as structured data, allowing teams to:

• Define clear schemas for content and datasets
• Validate and manage data centrally
• Serve content securely through APIs
• Power multiple frontends from a single backend

It is built for teams that care about data quality, strong contracts, and long-term maintainability.

---

🎯 Why FountainCMS?

Most CMS platforms are either:

• Too rigid for real-world, evolving data models
• Too abstract, hiding important data decisions behind UI layers

FountainCMS solves this by:

• Making schemas explicit and versionable
• Encouraging clean separation of concerns
• Prioritizing developer control and predictability

This makes it especially useful for data-heavy products, dashboards, internal tools, and modern web applications.

---

👥 Who is this for?

• Developers who want full control over content modeling
• Backend-first or API-driven teams
• Startups looking for a flexible, open CMS
• Teams managing datasets, metadata, or configuration-heavy content

---

📁 Repository Structure

fountaincms/
├── frontend/      # React + Vite frontend app
│   ├── src/
│   ├── public/
│   ├── vite.config.ts
│   ├── index.html
│   ├── package.json
│   └── tsconfig.json
├── backend/       # NestJS backend (TypeScript)
│   ├── src/
│   │   ├── content/
│   │   ├── roles/
│   │   ├── user/
│   │   └── ...
│   ├── test/
│   ├── package.json
│   ├── tsconfig.json
│   ├── jest.config.js
│   └── README.md
├── package.json   # Monorepo root (workspaces)
├── .gitmessage    # Conventional Commits template
├── .husky/        # Git hooks (commit-msg, pre-commit)
├── lint-staged.config.js
├── commitlint.config.js
├── SECURITY.md
├── CONTRIBUTING.md
├── .github/       # Issue/PR templates, workflows
├── .nvmrc         # Node.js version for development (v22.13.1)
└── README.md

---

Architecture

A. System Architecture Diagram This diagram shows the physical flow of the monorepo components.

graph LR
    subgraph Client
        A[React Frontend <br/> Vite] 
    end
    subgraph Server
        B[NestJS Backend <br/> REST API]
    end
    subgraph Database
        C[Prisma ORM]
        D[(PostgreSQL)]
    end
    A <-->|HTTP/JSON| B
    B <--> C
    C <--> D

Loading

B. Content Modeling Workflow A sequence diagram showing the "data-first" lifecycle of a single request.

sequenceDiagram
    participant FE as Frontend (React)
    participant CN as NestJS Controller
    participant SR as Service Logic
    participant PR as Prisma Client
    participant DB as Database (PostgreSQL)

    FE->>CN: GET /api/content/:id
    CN->>SR: Request Data Validation
    SR->>PR: Query Execution
    PR->>DB: SQL Select
    DB-->>PR: Raw Data
    PR-->>SR: Typed Object
    SR-->>CN: Processed Content
    CN-->>FE: JSON Response

Loading

C. Modular Backend Structure A flowchart to help contributors navigate the backend/src directory logic.

graph TD
    Root[backend/src] --> Auth[Auth Module]
    Root --> Content[Content Module]
    Root --> User[User Module]
    Root --> Roles[Roles Module]

    Content --> C_Ctrl[Controllers]
    Content --> C_Srv[Services]
    Content --> C_Ent[Entities/DTOs]
    
    Auth -.->|Guards| Content
    Roles -.->|Permissions| Content

Loading

---

🏁 Getting Started

Prerequisites

• Node.js (v22.13.1 required, see .nvmrc)
• npm (v7+ recommended for workspaces)

Install dependencies

At the root of the repository:

npm install

This installs dependencies for both frontend and backend using npm workspaces.

🗄 Database Setup (PostgreSQL)

Create DB User & Database

Open psql as postgres superuser:

sudo -u postgres psql

CREATE USER fountain_user WITH PASSWORD 'fountain_pass';
CREATE DATABASE fountain_db OWNER fountain_user;
ALTER USER fountain_user CREATEDB; -- required for Prisma migrate dev
\q

🔐 Frontend Environment Configuration

Create frontend .env:

cd frontend
nano .env

Copy the details from .env.sample to .env and save

🔐 Backend Environment Configuration

Create backend .env:

cd backend
nano .env

Copy the details from .env.sample to .env and save

🔑 Authentication

Auth is configurable via AUTH_MODE in backend .env:

• AUTH_MODE=local (default): Email/username + password. Users need a passwordHash in the DB (see seed).
• AUTH_MODE=oauth2: OAuth 2 / OIDC. Set OAUTH2_ISSUER, OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, and optionally claim mapping. Login redirects to your IdP, then callback sets a JWT cookie.
• AUTH_MODE=saml: SAML 2.0. Set SAML_ENTRY_POINT, SAML_IDP_CERT, SAML_ACS_URL, and optionally attribute mapping.

JWT is issued after any successful login (local or SSO) and sent in an HttpOnly cookie; the frontend also supports Bearer token for API clients. See backend/.env.sample for all auth-related variables.

🧬 Run Prisma Migrations

cd backend
npx prisma migrate dev --name init

This will:

• Create DB tables
• Generate Prisma Client
• Sync schema

---

▶️ Postgresql on docker

Install Docker and Docker Compose:

sudo apt update
sudo apt install docker.io docker-compose-plugin

Start Docker:

sudo systemctl start docker
sudo systemctl enable docker

Start PostgreSQL Using Docker Compose

From the project root directory:

docker compose up -d db

Backend Environment Configuration (Docker Database)

Ensure your backend/.env contains:

DATABASE_URL=postgresql://fountain_user:fountain_pass@localhost:5432/fountain_db?schema=public

Run Prisma Migrations

After the database container starts:

cd backend
npx prisma migrate dev --name init

Running Full Stack Using Docker (Backend + Database)

To start backend and database together:

docker compose up --build

This will:

• Start PostgreSQL
• Build and run backend service
• Expose backend at: http://localhost:4000

---

▶️ Running the Project

Run frontend + backend together

npm run dev

Starts both services in parallel using concurrently.

Run Frontend only

npm run dev:frontend

Run Backend only

npm run dev:backend

---

📚 API Documentation (Swagger)

Once the backend is running:

http://localhost:4000/api-docs

---

🧪 Linting, Formatting, and Testing

• Linting and formatting are enforced via Husky and lint-staged

• Run all tests:

  npm test

• Pre-commit hooks will block commits if checks fail

---

📝 Git Commit Message Template

This project follows Conventional Commits.

Enable commit template locally

git config --local commit.template .gitmessage

---

📦 Release Management & Changelog

• Follows Keep a Changelog
• Uses Semantic Versioning

Tagging a Release

1. Update CHANGELOG.md

2. Commit:

   git commit -m "chore(release): update changelog for vX.Y.Z"

3. Tag and push:

   git tag vX.Y.Z
   git push origin vX.Y.Z --follow-tags

---

🤝 Contributing & Security

• See CONTRIBUTING.md
• See SECURITY.md

---

🌱 Community & Announcements

🚀 Migration Complete

The backend has been migrated from Express to NestJS for:

• Better scalability and modularity
• Improved type safety
• Cleaner architecture

---

🤝 Get Involved

We welcome contributors of all experience levels:

• Build features and integrations
• Fix bugs
• Improve docs and DX
• Review and test code

👉 Check:

• Issues
• Discussions

---

❤️ Our Contributors

---