sutramd

SutraMD

A modern blog platform with a Next.js frontend and NestJS API backend, built as an Nx monorepo.

Table of Contents

• SutraMD
  • Table of Contents
  • Overview
  • Architecture
    • Data Flow
  • Tech Stack
  • Getting Started
    • Prerequisites
    • Installation
  • Development
    • Starting Development Servers
    • Working with Nx
  • Project Structure
  • Available Commands
  • Database
    • Database Schema
    • Migrations
  • API Documentation
  • Deployment
    • Preparing for Production
    • Deployment Options
  • Contributing
  • License

Overview

SutraMD is a modern blogging platform that allows users to create, manage, and publish markdown-based content. The application provides a clean user interface for writing and organizing blog posts, with robust backend services for content management.

Architecture

This project is built as an Nx monorepo with the following main applications:

• Frontend: A Next.js application for the user-facing interface
• API: A NestJS application providing RESTful services
• Shared Libraries: Common code shared between applications

Data Flow

[Frontend (Next.js)] <---HTTP/REST---> [API (NestJS)] <---EdgeDB/GEL---> [Database]
       │                                     │
       │                                     │
       └──────────shared types──────────────┘
                (through libs)

Tech Stack

• Frontend:

  • Next.js
  • React
  • TailwindCSS
  • TypeScript

• Backend:

  • NestJS
  • EdgeDB with GEL
  • TypeScript

• Tooling:

  • Nx monorepo
  • ESLint
  • Jest
  • GitHub Actions

Getting Started

Prerequisites

• Node.js 16+
• Yarn
• EdgeDB

Installation

1. Clone the repository:

    
   tsx
   git clone https://github.com/yourusername/sutramd.git
   cd sutramd
   

2. Install dependencies:

    
   tsx
   yarn install
   

3. Set up environment variables:

    
   tsx
   # For API
   cp apps/api/.env.example apps/api/.env
   # Update with your database credentials
   

4. Start the EdgeDB database:

    
   tsx
   # If you have Docker installed
   docker-compose up -d edgedb
   
   # Or if you have EdgeDB CLI
   edgedb project init
   

5. Build the projects:

    
   tsx
   yarn build
   

Development

Starting Development Servers

To start both the API and frontend in development mode:

 
tsx
# Start everything
yarn dev

# Start only API
yarn start:api

# Start only frontend
yarn start:frontend

Working with Nx

This project uses Nx for managing the monorepo. Some useful commands:

 
tsx
# Run a command on a specific project
nx run [project]:[command]

# Run a command only on projects affected by your changes
nx affected --target=[command]

# Visualize your project dependency graph
nx graph

Project Structure

sutramd/
├── apps/
│   ├── api/               # NestJS Backend
│   │   ├── src/
│   │   │   ├── blog/      # Blog functionality
│   │   │   ├── auth/      # Authentication services
│   │   │   ├── user/      # User management
│   │   │   ├── geldata/   # EdgeDB connection services
│   │   │   └── dbschema/  # Generated database schema
│   │   └── project.json   # API build configuration
│   ├── frontend/          # Next.js Frontend
│   │   ├── src/
│   │   │   ├── pages/     # Next.js page components
│   │   │   ├── components/# Reusable React components
│   │   │   └── icons/     # UI icons
│   │   ├── lib/           # Utility functions
│   │   └── styles/        # CSS and styling
│   └── api-e2e/           # API End-to-End Tests
├── libs/
│   └── gel/               # Shared EdgeDB/GEL Library
└── nx.json                # Nx Configuration

Available Commands

Database

SutraMD uses EdgeDB with the GEL client for database operations. The database schema is defined in the API project and schemas are automatically generated.

Database Schema

The main entities in the database are:

• User: Authentication and user management
• MarkdownFile: Blog post content
• Folder: Organization structure for content

Migrations

To run database migrations:

 
tsx
cd apps/api
yarn migrate:dev

API Documentation

The API documentation is available through Swagger UI when running the API server:

http://localhost:3001/docs

Key API endpoints:

• /blog: Blog post management
• /auth: Authentication
• /user: User management

Deployment

Preparing for Production

1. Build all projects:

    
   tsx
   yarn build
   

2. Set production environment variables:

   # In your production environment
   NODE_ENV=production
   

Deployment Options

• Frontend: Can be deployed to Vercel, Netlify, or any static hosting service
• API: Can be deployed to any Node.js hosting service like Heroku, AWS, or GCP

Contributing

1. Fork the repository
2. Create a feature branch:

    
   tsx
   git checkout -b feature/your-feature-name
   

3. Make your changes
4. Run tests and linting:

    
   tsx
   yarn affected:test
   yarn affected:lint
   

5. Commit your changes:

    
   tsx
   git commit -m "Add some feature"
   

6. Push to the branch:

    
   tsx
   git push origin feature/your-feature-name
   

7. Create a pull request

License

MIT