datacops-cms/README.md

A modern, extensible CMS built with Next.js and Prisma.

# DataCops CMS

A powerful, flexible headless Content Management System built with Next.js 15, TypeScript, and Prisma. DataCops CMS provides a modern, user-friendly interface for content management with dynamic content type creation, API management, and role-based access control.

## ✨ Features

### 🏗️ Content Management

- **Dynamic Content Types**: Create and manage custom content types with a visual builder
- **Rich Content Editor**: Built-in TinyMCE editor for rich text content
- **Media Management**: File upload and management system
- **Content Versioning**: Draft, Published, and Scheduled status support
- **Bulk Operations**: Manage multiple content items efficiently

### 🔐 Authentication & Security

- **NextAuth.js Integration**: Secure authentication system
- **Role-Based Access Control**: SUPERADMIN, ADMIN, and USER roles
- **API Permissions**: Granular control over API endpoint access
- **Middleware Protection**: Route-level security with automatic redirects

### 🛠️ API Management

- **RESTful APIs**: Auto-generated APIs for all content types
- **Endpoint Monitoring**: View and manage all available API endpoints
- **Permission Control**: Configure HTTP method permissions per content type
- **API Documentation**: Built-in endpoint documentation

### 🎨 Modern UI/UX

- **Responsive Design**: Mobile-first design with Tailwind CSS
- **Dark/Light Mode**: Built-in theme switching
- **Component Library**: Radix UI components with custom styling
- **Interactive Dashboard**: Real-time data visualization
- **Sidebar Navigation**: Collapsible navigation with search

### ⚙️ Developer Experience

- **TypeScript**: Full type safety throughout the application
- **Hot Reload**: Development supervisor with automatic restarts
- **Database Agnostic**: Support for SQLite, PostgreSQL, and MySQL
- **Schema Generation**: Automatic Prisma schema updates
- **ESLint & Prettier**: Code quality and formatting tools

## 🚀 Quick Start

### Prerequisites

- Node.js 18+
- pnpm (recommended) or npm
- Database (SQLite for development, PostgreSQL/MySQL for production)

### Installation

1. **Clone the repository**

   ```bash
   git clone <repository-url>
   cd datacops-cms
   ```

2. **Install dependencies**

   ```bash
   pnpm install
   ```

3. **Start the development server**

   ```bash
   pnpm dev
   ```

4. **Open your browser**
   Navigate to [http://localhost:3000](http://localhost:3000)

5. **Complete the installation**
   - Follow the installation wizard
   - Configure your database connection
   - Create your admin account
   - Start building!

## 📦 Technology Stack

### Core Technologies

- **[Next.js 15](https://nextjs.org/)** - React framework with App Router
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
- **[Prisma](https://www.prisma.io/)** - Database ORM with type safety
- **[NextAuth.js](https://next-auth.js.org/)** - Authentication library
- **[TanStack Query](https://tanstack.com/query)** - Server state management

### UI & Styling

- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework
- **[Radix UI](https://www.radix-ui.com/)** - Accessible component primitives
- **[Lucide React](https://lucide.dev/)** - Beautiful icon library
- **[Vaul](https://vaul.emilkowal.ski/)** - Drawer component

### Development Tools

- **[ESLint](https://eslint.org/)** - Code linting
- **[Chokidar](https://github.com/paulmillr/chokidar)** - File watching
- **[Axios](https://axios-http.com/)** - HTTP client

## 🏗️ Project Structure

```
datacops-cms/
├── app/                          # Next.js App Router
│   ├── (dashboard)/             # Dashboard layout group
│   │   ├── admin/               # Admin panel pages
│   │   │   ├── content/         # Content management
│   │   │   ├── content-types/   # Content type builder
│   │   │   ├── endpoints/       # API endpoint management
│   │   │   └── permissions/     # Permission management
│   │   └── page.tsx            # Dashboard home
│   ├── api/                     # API routes
│   │   ├── auth/               # Authentication endpoints
│   │   ├── content/            # Content CRUD operations
│   │   ├── content-types/      # Content type management
│   │   ├── endpoints/          # Endpoint listing
│   │   ├── permissions/        # Permission management
│   │   └── install/            # Installation endpoint
│   ├── install/                # Installation wizard
│   ├── login/                  # Authentication pages
│   ├── layout.tsx              # Root layout
│   └── globals.css             # Global styles
├── components/                  # Reusable components
│   ├── ui/                     # UI component library
│   ├── app-sidebar.tsx         # Main sidebar navigation
│   └── login-form.tsx          # Authentication forms
├── lib/                        # Utility libraries
│   ├── prisma.ts              # Prisma client
│   ├── utils.ts               # General utilities
│   └── axios.ts               # HTTP client setup
├── prisma/                     # Database schema
│   └── schema.prisma          # Prisma schema definition
├── content/                    # Content storage
├── content-types/              # Content type definitions
├── scripts/                    # Build and development scripts
│   ├── dev-supervisor.js      # Development file watcher
│   └── generate-prisma-schema.ts # Schema generation
├── types/                      # TypeScript type definitions
└── hooks/                      # Custom React hooks
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the root directory:

```env
# Database
DATABASE_URL="file:./dev.db"  # SQLite for development
# DATABASE_URL="postgresql://user:password@localhost:5432/datacops" # PostgreSQL
# DATABASE_URL="mysql://user:password@localhost:3306/datacops" # MySQL

# NextAuth
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# Installation Status
IS_INSTALLED="false"  # Set to "true" after installation
```

### Database Setup

#### SQLite (Development)

SQLite is configured by default and requires no additional setup.

#### PostgreSQL (Production)

```bash
# Install PostgreSQL client
npm install pg @types/pg

# Update DATABASE_URL in .env.local
DATABASE_URL="postgresql://username:password@localhost:5432/datacops_cms"
```

#### MySQL (Production)

```bash
# Install MySQL client
npm install mysql2

# Update DATABASE_URL in .env.local
DATABASE_URL="mysql://username:password@localhost:3306/datacops_cms"
```

## 🎯 Usage Guide

### Content Type Management

1. **Creating Content Types**

   - Navigate to Admin → Content Type Builder
   - Click "Create new type"
   - Define fields with various types (text, number, date, relation, etc.)
   - Configure field validation and requirements

2. **Managing Content**
   - Access content through the sidebar navigation
   - Create, edit, and delete content items
   - Set content status (Draft, Published, Scheduled)
   - Use the rich text editor for formatted content

### API Usage

All content types automatically generate RESTful APIs:

```
GET    /api/content/[type]      # List all items
POST   /api/content/[type]      # Create new item
GET    /api/content/[type]/[id] # Get specific item
PUT    /api/content/[type]/[id] # Update item
DELETE /api/content/[type]/[id] # Delete item
```

### Permission Management

Configure API access permissions:

- Navigate to Admin → API Permissions
- Toggle HTTP methods for each content type
- Control which endpoints are publicly accessible

## 🚀 Deployment

### Prerequisites for Production

1. **Environment Setup**

   ```bash
   # Set production environment variables
   NODE_ENV=production
   IS_INSTALLED=true
   DATABASE_URL=your-production-database-url
   NEXTAUTH_SECRET=your-secure-secret
   NEXTAUTH_URL=your-production-domain
   ```

2. **Database Migration**
   ```bash
   # Generate and apply migrations
   npx prisma migrate deploy
   npx prisma generate
   ```

### Vercel Deployment

1. **Connect your repository** to Vercel
2. **Configure environment variables** in Vercel dashboard
3. **Deploy** - Vercel will automatically build and deploy your application

### Self-Hosted Deployment

1. **Build the application**

   ```bash
   pnpm build
   ```

2. **Start the production server**
   ```bash
   pnpm start
   ```

## 🛠️ Development

### Available Scripts

```bash
# Development with file watching
pnpm dev

# Development with Turbopack
pnpm dev-turbo

# Production build
pnpm build

# Start production server
pnpm start

# Code linting
pnpm lint
```

### Development Workflow

1. **Start development server**

   ```bash
   pnpm dev
   ```

2. **The development supervisor will:**

   - Watch for file changes
   - Automatically restart the server
   - Regenerate Prisma schema when needed
   - Handle port conflicts

3. **Code with hot reload** - Changes are reflected immediately

### Custom Development

#### Adding New Content Types Programmatically

Content types are stored as JSON files in the `content-types/` directory:

```json
{
	"value": "blog-post",
	"label": "Blog Post",
	"fields": [
		{
			"name": "title",
			"label": "Title",
			"type": "text",
			"required": true
		},
		{
			"name": "content",
			"label": "Content",
			"type": "richtext"
		}
	]
}
```

#### Extending the API

Add custom API routes in the `app/api/` directory following Next.js conventions.

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **Commit your changes** (`git commit -m 'Add amazing feature'`)
4. **Push to the branch** (`git push origin feature/amazing-feature`)
5. **Open a Pull Request**

### Development Guidelines

- Follow TypeScript best practices
- Add tests for new features
- Update documentation as needed
- Follow the existing code style
- Ensure all tests pass before submitting

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: Check this README and inline code comments
- **Issues**: Report bugs and request features via GitHub Issues
- **Discussions**: Join community discussions in GitHub Discussions

## 🙏 Acknowledgments

- **Next.js Team** for the amazing React framework
- **Prisma Team** for the excellent database toolkit
- **Radix UI Team** for accessible component primitives
- **Vercel** for hosting and deployment platform
- **Open Source Community** for the incredible ecosystem

---

Built with ❤️ for the DataCops project.