notely/QUICKSTART.md

🚀 Quick Start Guide

Prerequisites

• Docker and Docker Compose (recommended for quickest setup)
• OR: Go 1.21+, Node.js 18+, MongoDB 7.0+

Option 1: Docker Compose (Recommended - 1 Command)

# Clone/navigate to project
cd noteapp

# Start everything
docker-compose up

# Wait for services to initialize (~30 seconds)
# Then open: http://localhost

Services running:

• Notely: http://localhost:8080
• MongoDB: localhost:27017
• Nginx Reverse Proxy: http://localhost:80

Test user (after startup):

• Register a new account at http://localhost/register
• Login and create a Space
• Add Categories and Notes

Option 2: Local Development

Backend Setup

cd backend

# Copy environment file
cp .env.example .env

# Install dependencies
go mod download

# Ensure MongoDB is running
# Docker: docker run -d -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=admin \
#   -e MONGO_INITDB_ROOT_PASSWORD=password mongo:7.0-alpine

# Run backend
go run ./cmd/server/main.go

# Logs should show: "Server starting on port 8080"

Frontend Setup

cd frontend

# Copy environment file
cp .env.example .env

# Install dependencies
npm install

# Start dev server
npm run dev

# Open: http://localhost:5173 in browser

🧪 Testing

Backend Tests

cd backend

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific test
go test -v -run TestRegisterUser ./tests/unit/...

# With coverage
go test -cover ./...

Frontend Tests

cd frontend

# Run tests
npm run test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage

📝 Key API Endpoints

Authentication

# Register
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "username": "myuser",
    "password": "SecurePassword123",
    "password_confirm": "SecurePassword123",
    "first_name": "John",
    "last_name": "Doe"
  }'

# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123"
  }'

# Response contains: access_token, refresh_token, user data

Create Space

curl -X POST http://localhost:8080/api/v1/spaces \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Space",
    "description": "Notes for my project",
    "icon": "📚",
    "is_public": false
  }'

Create Note

curl -X POST http://localhost:8080/api/v1/spaces/{spaceId}/notes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Note",
    "content": "# Markdown Heading\n\nThis is a note",
    "tags": ["important", "work"],
    "category_id": null,
    "is_pinned": false,
    "is_favorite": true
  }'

Search Notes

curl "http://localhost:8080/api/v1/spaces/{spaceId}/notes/search?q=important" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

🔍 Troubleshooting

MongoDB Connection Error

Error: Failed to connect to database

Solution:
docker run -d -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=password \
  mongo:7.0-alpine

Port Already in Use

# Find process on port 8080
lsof -i :8080

# Kill it
kill -9 <PID>

# Or use different port
PORT=8081 go run ./cmd/server/main.go

CORS Errors

Make sure frontend and backend URLs match in:

• Frontend: VITE_API_BASE_URL in .env
• Backend: CORS_ALLOWED_ORIGINS in .env

MongoDB Auth Failed

If using Docker Compose:

• Username: admin
• Password: password
• Connection string includes ?authSource=admin

📚 Project Structure

noteapp/
├── backend/                    # Go REST API
│   ├── cmd/server/            # Entry point
│   ├── internal/
│   │   ├── domain/            # Business logic
│   │   ├── application/       # Services & DTOs
│   │   ├── infrastructure/    # DB, auth, security
│   │   └── interfaces/        # HTTP handlers
│   ├── tests/                 # Test files
│   ├── go.mod & go.sum        # Dependencies
│   └── README.md
│
├── frontend/                   # Vue 3 SPA
│   ├── src/
│   │   ├── components/        # UI components
│   │   ├── pages/             # Page components
│   │   ├── stores/            # Pinia state
│   │   ├── services/          # API client
│   │   ├── router/            # Vue Router
│   │   ├── assets/            # Styles & images
│   │   └── main.js            # Entry point
│   ├── tests/                 # Test files
│   ├── package.json           # Dependencies
│   └── vite.config.js         # Vite configuration
│
├── devops/
│   ├── docker/
│   │   ├── Dockerfile.backend
│   │   ├── Dockerfile.frontend
│   │   └── nginx.conf
│   └── kubernetes/
│       └── deployment.yaml
│
├── docker-compose.yml         # Local development setup
├── README.md                  # Project docs
├── ARCHITECTURE.md            # Architecture overview
├── SECURITY.md                # Security implementation
└── ENV_SETUP.md               # Environment configuration

🎓 Learning Resources

Understanding the Code

1. Start here: ARCHITECTURE.md - Clean architecture pattern
2. Then read: Backend domain/entities/*.go - Core models
3. Next: Backend application/services/*.go - Business logic
4. UI: Frontend src/stores/authStore.js - State management
5. API: Backend interfaces/handlers/*.go - HTTP layer

Security Deep Dive

See SECURITY.md for:

• Password hashing (Argon2id)
• JWT authentication
• Authorization (RBAC)
• Input validation
• XSS prevention
• CSRF protection

🚀 Next Steps

1. Explore the UI: Create spaces, notes, categories
2. Read the code: Start with index ARCHITECTURE.md
3. Run tests: go test ./... and npm test
4. Deploy: Use docker-compose.yml or Kubernetes
5. Extend: Add OAuth2, WebSockets, more features

💡 Quick Tips

• Hot reload: Changes auto-reload in dev mode
• Network tab: Check API calls in browser DevTools
• Logs: Docker: docker-compose logs -f service-name
• Database GUI: MongoDB Compass (free tool to browse data)
• API testing: Postman or curl commands

📞 Support

• Check logs: docker-compose logs
• Review SECURITY.md for auth issues
• Check ENV_SETUP.md for config problems
• See ARCHITECTURE.md for code structure

---

Now you're ready to explore and extend Notely! 🎉