Skip to content

README.md

Latest commit

 

History

History
261 lines (188 loc) · 5.95 KB

README.md

File metadata and controls

261 lines (188 loc) · 5.95 KB

NotesVerb - Microservices Note-Taking Application

A modern, scalable note-taking application built with microservices architecture using Node.js, TypeScript, and PostgreSQL.

🏗️ Architecture Overview

NotesVerb follows a microservices architecture pattern with the following services:

  • API Gateway (Port 8080) - Central entry point, routing, and authentication
  • Auth Service (Port 3001) - User authentication and JWT token management
  • User Service (Port 3002) - User profile management
  • Notes Service (Port 3003) - Note creation, retrieval, and management
  • Tags Service (Port 3004) - Tag management and organization

Each service has its own PostgreSQL database following the database-per-service pattern.

🚀 Tech Stack

  • Runtime: Node.js with TypeScript
  • Framework: Express.js
  • Database: PostgreSQL with Prisma ORM
  • Authentication: JWT tokens
  • Containerization: Docker & Docker Compose
  • Testing: Jest
  • Security: Helmet, CORS, bcrypt

📋 Prerequisites

  • Node.js (v18 or higher)
  • Docker and Docker Compose
  • PostgreSQL (if running without Docker)
  • Git

🛠️ Quick Start

1. Clone the Repository

git clone https://github.com/fiston-user/notesverb-yt.git
cd notesverb-yt

2. Environment Setup

Copy the environment example files and configure them:

# Root environment file
cp .env.example .env

# API Gateway
cp api-gateway/.env.example api-gateway/.env

# Services
cp services/auth-service/.env.example services/auth-service/.env
cp services/user-service/.env.example services/user-service/.env
cp services/notes-service/.env.example services/notes-service/.env
cp services/tags-service/.env.example services/tags-service/.env

3. Update Environment Variables

Edit the .env files and update the following critical values:

  • JWT_SECRET - Use a strong, random secret (minimum 256 bits)
  • JWT_REFRESH_SECRET - Use a different strong, random secret
  • Database passwords (if not using default Docker setup)

Generate secure secrets:

# Generate JWT secrets
openssl rand -base64 32

4. Start the Database

docker-compose up postgres -d

5. Install Dependencies

# Install dependencies for all services
npm install

# Or install individually
cd api-gateway && npm install
cd ../services/auth-service && npm install
cd ../user-service && npm install
cd ../notes-service && npm install
cd ../tags-service && npm install
cd ../shared && npm install

6. Database Setup

Run Prisma migrations for each service:

# Auth Service
cd services/auth-service
npx prisma migrate dev
npx prisma generate

# User Service
cd ../user-service
npx prisma migrate dev
npx prisma generate

# Notes Service
cd ../notes-service
npx prisma migrate dev
npx prisma generate

# Tags Service
cd ../tags-service
npx prisma migrate dev
npx prisma generate

7. Start the Services

Start each service in development mode:

# Terminal 1 - Auth Service
cd services/auth-service
npm run dev

# Terminal 2 - User Service
cd services/user-service
npm run dev

# Terminal 3 - Notes Service
cd services/notes-service
npm run dev

# Terminal 4 - Tags Service
cd services/tags-service
npm run dev

# Terminal 5 - API Gateway
cd api-gateway
npm run dev

📡 API Endpoints

Authentication

  • POST /api/auth/register - User registration
  • POST /api/auth/login - User login
  • POST /api/auth/refresh - Refresh tokens
  • POST /api/auth/logout - User logout

Users

  • GET /api/users/profile - Get user profile
  • PUT /api/users/profile - Update user profile

Notes

  • POST /api/notes - Create a note
  • GET /api/notes - Get user's notes
  • GET /api/notes/:id - Get specific note

Tags

  • POST /api/tags - Create a tag
  • GET /api/tags - Get user's tags

🧪 Testing

Run tests for each service:

# Auth Service
cd services/auth-service
npm test

# User Service
cd services/user-service
npm test

# Notes Service
cd services/notes-service
npm test

🐳 Docker Deployment

Full Stack with Docker Compose

# Build and start all services
docker-compose up --build

# Start in detached mode
docker-compose up -d

# Stop all services
docker-compose down

🔒 Security Considerations

  1. Environment Variables: Never commit .env files to version control
  2. JWT Secrets: Use strong, unique secrets in production
  3. Database Credentials: Use secure passwords and restrict access
  4. CORS: Configure appropriate origins for your frontend
  5. HTTPS: Use HTTPS in production environments

📁 Project Structure

notesverb/
├── api-gateway/          # API Gateway service
├── services/
│   ├── auth-service/     # Authentication service
│   ├── user-service/     # User management service
│   ├── notes-service/    # Notes management service
│   └── tags-service/     # Tags management service
├── shared/               # Shared utilities and types
├── docker-compose.yml    # Docker services configuration
├── init-database.sql     # Database initialization
└── README.md

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass
  6. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Troubleshooting

Common Issues

  1. Port conflicts: Ensure ports 3001-3004 and 8080 are available
  2. Database connection: Verify PostgreSQL is running and credentials are correct
  3. JWT errors: Ensure JWT_SECRET is consistent across all services
  4. CORS issues: Check CORS_ORIGIN configuration matches your frontend URL

Health Checks

Each service provides a health check endpoint:

  • API Gateway: http://localhost:8080/health
  • Auth Service: http://localhost:3001/health
  • User Service: http://localhost:3002/health
  • Notes Service: http://localhost:3003/health
  • Tags Service: http://localhost:3004/health