🚀 Fragments - Cloud-Native Microservice API

A production-ready RESTful API for managing content fragments with advanced format conversion capabilities

Features • Tech Stack • Getting Started • API Overview • Architecture

---

📋 Project Overview

Fragments is a scalable, cloud-native microservice that enables users to store, manage, and convert various types of content fragments. Built with modern development practices, this API demonstrates proficiency in backend development, cloud services, and software engineering principles.

Key Highlights:

• 🔐 Secure authentication using AWS Cognito and JWT
• 🗄️ Persistent storage with AWS DynamoDB and S3
• 🔄 Intelligent format conversion (text, markdown, images, JSON, YAML, CSV)
• 📊 Production-grade logging with Pino
• 🐳 Containerized deployment with Docker
• ✅ Comprehensive testing with Jest
• 🛡️ Security best practices with Helmet and CORS

---

✨ Features

Content Management

• Multi-format Support: Handle text, markdown, HTML, CSV, JSON, YAML, and images (PNG, JPEG, WebP, AVIF, GIF)
• CRUD Operations: Create, read, update, and delete fragments with ease
• Format Conversion: Automatically convert between compatible formats
  • Markdown → HTML/Plain Text
  • CSV → JSON
  • JSON → YAML
  • Images → Multiple formats using Sharp

Cloud Integration

• AWS DynamoDB: Fast, scalable NoSQL database for metadata
• AWS S3: Reliable object storage for fragment data
• AWS Cognito: Enterprise-grade authentication and authorization

Developer Experience

• Hot Reload: Fast development with Nodemon
• Debug Mode: Built-in debugging support for VS Code and Chrome DevTools
• Comprehensive Logging: Structured logging with configurable levels
• Code Quality: ESLint and Prettier for consistent code style
• Testing Suite: Unit and integration tests with Jest and Hurl

---

🛠 Tech Stack

Backend Framework

• Node.js - JavaScript runtime
• Express.js 5.x - Fast, unopinionated web framework
• Passport.js - Authentication middleware

Cloud Services

• AWS DynamoDB - NoSQL database for fragment metadata
• AWS S3 - Object storage for fragment data
• AWS Cognito - User authentication and JWT verification

Libraries & Tools

• Sharp - High-performance image processing
• Markdown-it - Markdown parser and compiler
• Pino - Fast JSON logger
• Helmet - Security middleware
• CORS - Cross-origin resource sharing
• Compression - Response compression

Development Tools

• Docker - Containerization
• Docker Compose - Multi-container orchestration
• Jest - Testing framework
• Hurl - Integration testing
• ESLint - Code linting
• Prettier - Code formatting
• Nodemon - Development server with hot reload

---

🚀 Getting Started

Prerequisites

Node.js >= 14.x
npm >= 6.x
Docker (optional, for containerized deployment)

Installation

1. Clone the repository

   git clone https://github.com/yasinhajilou/fragments.git
   cd fragments

2. Install dependencies

   npm install

3. Configure environment variables

   cp debug.env.example debug.env
   # Edit debug.env with your AWS credentials and configuration

4. Start the development server

   npm run dev

The API will be available at http://localhost:8080

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build

# Run in detached mode
docker-compose up -d

---

📡 API Overview

Fragment Endpoints

Method	Endpoint	Description
POST	/v1/fragments	Create a new fragment
GET	/v1/fragments	Get all fragments for authenticated user
GET	/v1/fragments/:id	Get a specific fragment
GET	/v1/fragments/:id.:ext	Get fragment with format conversion
PUT	/v1/fragments/:id	Update an existing fragment
DELETE	/v1/fragments/:id	Delete a fragment
GET	/v1/fragments/:id/info	Get fragment metadata

Supported Formats

Text Formats:

• text/plain - Plain text
• text/markdown - Markdown
• text/html - HTML
• text/csv - CSV

Data Formats:

• application/json - JSON
• application/yaml - YAML

Image Formats:

• image/png - PNG
• image/jpeg - JPEG
• image/webp - WebP
• image/avif - AVIF
• image/gif - GIF

Format Conversion Examples

# Convert markdown to HTML
GET /v1/fragments/{id}.html

# Convert CSV to JSON
GET /v1/fragments/{id}.json

# Convert PNG to JPEG
GET /v1/fragments/{id}.jpg

# Convert JSON to YAML
GET /v1/fragments/{id}.yaml

---

🏗 Architecture

Project Structure

fragments/
├── src/
│   ├── app.js              # Express application setup
│   ├── index.js            # Application entry point
│   ├── server.js           # HTTP server configuration
│   ├── auth/               # Authentication strategies
│   ├── model/              # Database layer
│   ├── models/             # Data models
│   │   └── fragment.js     # Fragment class with conversion logic
│   ├── routes/             # API routes
│   │   ├── index.js        # Route definitions
│   │   └── api/            # API endpoints
│   ├── logger/             # Logging configuration
│   ├── response.js         # Response utilities
│   └── hash.js             # Hashing utilities
├── tests/
│   ├── unit/               # Unit tests
│   └── integration/        # Integration tests with Hurl
├── scripts/                # Utility scripts
├── .github/                # GitHub workflows (CI/CD)
├── Dockerfile              # Container configuration
├── docker-compose.yml      # Multi-container setup
├── jest.config.js          # Jest configuration
├── eslint.config.mjs       # ESLint rules
└── package.json            # Dependencies and scripts

Design Patterns

• MVC Architecture: Separation of concerns with models, routes, and controllers
• Middleware Pattern: Modular request processing pipeline
• Factory Pattern: Fragment creation and management
• Repository Pattern: Database abstraction layer

---

🧪 Testing

Run Unit Tests

npm test

Run Tests with Coverage

npm run coverage

Run Integration Tests

npm run test:integration

Watch Mode (for TDD)

npm run test:watch

---

📜 Available Scripts

Command	Description
npm start	Run in production mode
npm run dev	Run with hot reload (debug logging)
npm run debug	Run with Node.js inspector enabled
npm test	Run unit tests
npm run test:watch	Run tests in watch mode
npm run test:integration	Run integration tests
npm run coverage	Generate test coverage report
npm run lint	Check code quality with ESLint

---

🔒 Security Features

• Helmet.js: Security headers and protection against common vulnerabilities
• CORS: Configurable cross-origin resource sharing
• JWT Verification: Secure token-based authentication with AWS Cognito
• Input Validation: Type checking and sanitization
• Error Handling: Secure error responses without sensitive data leakage

---

📊 Performance Optimizations

• Compression: Gzip/Brotli response compression
• Efficient Logging: Fast JSON logging with Pino
• Async Operations: Non-blocking I/O for database and file operations
• Image Processing: Hardware-accelerated image conversion with Sharp
• Graceful Shutdown: Proper cleanup with Stoppable

---

🎓 Learning Outcomes

This project demonstrates proficiency in:

✅ Backend Development: RESTful API design, Express.js, Node.js
✅ Cloud Computing: AWS services (DynamoDB, S3, Cognito)
✅ DevOps: Docker, containerization, CI/CD practices
✅ Testing: Unit testing, integration testing, TDD
✅ Security: Authentication, authorization, secure coding
✅ Software Engineering: Clean code, design patterns, documentation
✅ Database Design: NoSQL data modeling, efficient queries
✅ API Design: RESTful principles, versioning, error handling

---

👨‍💻 Developer

Yasin Hajilou

Passionate about building scalable, cloud-native applications with modern technologies. This project showcases my ability to design and implement production-ready backend systems with best practices in mind.

---

📄 License

UNLICENSED - Educational project for BTI Semester 5

---

Built with ❤️ for learning and growth

⭐ If you find this project interesting, please consider giving it a star!