QuillSpace - Project Overview & Run Guide

This document provides a complete overview of the QuillSpace project, including architecture, technology stack and step‑by‑step instructions to run the system locally - for development.

---

1. Project Introduction

QuillSpace is a modern web platform designed as a flexible workspace / editor / dashboard system with:

• Strict separation between frontend and backend
• Well‑structured state management and data fetching
• A foundation that is easy to maintain and scale

The project consists of two main parts:

• Backend: Spring Boot (Java 17)
• Frontend: React 18, TypeScript, Vite, Tailwind CSS v4

---

2. High‑Level Architecture

[ React Frontend ]  <── HTTP / JSON ──>  [ Spring Boot Backend ]  <──>  [ PostgreSQL ]

• Backend acts purely as an API server
• Frontend handles UI, routing, authorization logic and state
• Database runs independently via Docker

---

3. Backend - QuillSpace Backend

• First, to run backend, please navigate to backend.

3.1 Technologies

• Java 17
• Spring Boot
• Gradle
• PostgreSQL
• Docker & Docker Compose

---

3.2 Prerequisites

Before running the backend, make sure you have:

• JDK 17 installed and JAVA_HOME configured
• Docker (Docker Desktop or Docker Engine) running

---

3.3 Database Setup (PostgreSQL)

The backend uses PostgreSQL running inside a Docker container.

Start the database with:

docker-compose up -d

• PostgreSQL will be exposed on port 5436

---

3.4 Running the Backend (Development Mode)

Windows (PowerShell / CMD)

.\gradlew bootRun

Linux / macOS

./gradlew bootRun

The backend will start on:

http://localhost:8080

---

3.5 Building & Running the JAR

Step 1: Build the project

Windows:

.\gradlew build

Linux / macOS:

./gradlew build

Step 2: Run the JAR file

After building, the JAR file will be located in:

build/libs/backend-0.0.1-SNAPSHOT.jar

Run it using:

java -jar build/libs/backend-0.0.1-SNAPSHOT.jar

---

3.6 Managing Dependencies

If you modify build.gradle (for example, add new libraries), refresh dependencies:

Windows:

.\gradlew build --refresh-dependencies

Linux / macOS:

./gradlew build --refresh-dependencies

---

4. Frontend - QuillSpace Frontend

• First, to run frontend, please navigate to frontend.

4.1 Technologies

Core

• React 19
• Vite 7
• TypeScript 5.8

Styling & UI

• Tailwind CSS v4
• Radix UI
• Lucide React Icons
• Custom UI Kit (src/uikit)

State & Data

• TanStack Query (React Query)
• Redux Toolkit
• Axios (with interceptors)

Forms & Validation

• React Hook Form
• Zod

---

4.2 Requirements

• Node.js LTS (v20+) recommended
• npm / yarn / pnpm

---

4.3 Installation & Running

Step 1: Clone the repository

git clone <repository-url>
cd frontend

Step 2: Install dependencies

npm install

Step 3: Run development server

npm run dev

Frontend will be available at:

http://localhost:5173

---

4.4 Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run lint - Run ESLint
• npm run format - Run Prettier

---

5. Frontend Project Structure

src/
├── components/     # Shared application components
├── containers/     # Business logic & feature orchestration
├── core/           # Core configs (Axios, app setup)
├── hocs/           # Higher‑Order Components (Auth, Role, Permission)
├── hooks/          # Custom React hooks
├── layouts/        # App layouts
├── mock/           # Mock data for development
├── pages/          # Application pages
├── providers/      # Global providers (Redux, Query)
├── services/       # API services & query keys
├── store/          # Redux store & slices
├── uikit/          # Custom UI library (@uikit)
└── utils/          # Utility functions

---

6. Routing & Authorization

Roles

Supported roles:

• guest
• user
• manager
• admin

Route Types

• Public Routes - Accessible by everyone
• Auth Routes - Only for non‑authenticated users
• Protected Routes - Require authentication and proper role

Authorization via HOCs

Located in src/hocs/:

• withAuth - Requires authentication
• withGuest - Requires user to be logged out
• withRole - Restricts access by role
• withPermission - Restricts access by permission

Example:

const AdminPage = withRole(UsersPage, { requiredRoles: ["admin"] });

---

7. State Management Strategy

Server State - React Query

Used for:

• API data fetching
• Caching
• Background synchronization
• Optimistic updates

Key components:

• BaseApiService
• Centralized Query Keys
• Generic Query & Mutation hooks

---

Client State - Redux Toolkit

Used for:

• Authentication state
• UI preferences (theme, sidebar)
• Permission lists

Main slices:

• authSlice
• uiSlice
• permissionsSlice

---

8. Current Status

Completed

• Backend base setup with PostgreSQL
• Frontend architecture & routing
• Auth, Role, Permission system
• Redux Toolkit & React Query integration
• Base layouts & pages

Next Steps

• Connect backend APIs to frontend services
• Implement Profile & Settings pages
• Build Admin Users CRUD
• Harden security & error handling

---

9. Coding Conventions

• Components: PascalCase
• Hooks & utils: kebab‑case
• Types & Interfaces: PascalCase (no I prefix)
• API methods: get, create, update, delete
• Boolean helpers: is, has, should