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)

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
cd frontend

# Run tests
npm run test

# Watch mode
npm run test:watch

# Coverage
npm run test:coverage
```

## 📝 Key API Endpoints

### Authentication

```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
# 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! 🎉**