aurganize-backend/README.md

# Aurganize V6.2

**Comprehensive Business Operating System for project-based work between vendors and consumers.**

## 🎯 Project Overview

Aurganize V6.2 is a multi-tenant SaaS platform that enables seamless project management and collaboration between service vendors and their consumers. Built with modern technologies, it provides:

- **Dynamic Workflow Engine:** AI-powered conversations for work item management
- **Milestone Logic System:** Configurable conditions for milestone achievement
- **Payment Management:** Structured proof workflow without payment processing
- **Real-time Collaboration:** WebSocket-based live updates
- **Enterprise Security:** Row-Level Security (RLS) for data isolation

## 🏗️ Architecture

----- TO DO ---------

## 📋 Prerequisites

Before you begin, ensure you have the following installed:

- **Go:** 1.21 or higher ([Download](https://golang.org/dl/))
- **Node.js:** 18 or higher ([Download](https://nodejs.org/))
- **PostgreSQL:** 14 or higher ([Download](https://www.postgresql.org/download/))
- **Docker:** Latest version ([Download](https://www.docker.com/get-started))
- **Docker Compose:** Included with Docker Desktop
- **Git:** Latest version ([Download](https://git-scm.com/downloads))

**Verify installations:**
```bash
go version        # Should show: go version go1.21.x
node --version    # Should show: v18.x.x or higher
npm --version     # Should show: 9.x.x or higher
docker --version  # Should show: Docker version 24.x.x
psql --version    # Should show: psql (PostgreSQL) 14.x
git --version     # Should show: git version 2.x.x
```

## 🚀 Quick Start

### Option 1: Docker (Recommended)

**Fastest way to get started - everything runs in containers:**
```bash
# 1. Clone the repository
git clone https://github.com/yourorg/aurganize-v62.git
cd aurganize-v62

# 2. Start all services
docker-compose up -d

# 3. Run database migrations
docker-compose exec backend make migrate-up

# 4. Access the application
# Frontend: http://localhost:5173
# Backend:  http://localhost:8080
# API Docs: http://localhost:8080/api/v1/docs
```

**To stop services:**
```bash
docker-compose down
```

**To see logs:**
```bash
docker-compose logs -f backend    # Backend logs
docker-compose logs -f frontend   # Frontend logs
```

### Option 2: Local Development

**Run services natively (for development):**

#### Step 1: Setup Backend
```bash
cd backend

# Copy environment template
cp .env.example .env

# Edit .env with your database credentials
# nano .env

# Install dependencies
go mod download

# Run database migrations
make migrate-up

# Start development server (with hot reload)
make dev
```

Backend should now be running at `http://localhost:8080`

#### Step 2: Setup Frontend

**Open a new terminal:**
```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev
```

Frontend should now be running at `http://localhost:5173`

#### Step 3: Verify Everything Works
```bash
# Test backend health check
curl http://localhost:8080/health

# Expected response:
# {
#   "status": "healthy",
#   "version": "6.2.0",
#   "timestamp": "2025-11-26T10:00:00Z"
# }

# Open frontend in browser
# Visit: http://localhost:5173
```

## 📁 Project Structure

----- TO DO ---------


## 🛠️ Development Workflow

### Creating a New Feature
```bash
# 1. Ensure you're on develop branch
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/your-feature-name

# 3. Make your changes
# ... code, code, code ...

# 4. Run tests
cd backend && make test
cd frontend && npm test

# 5. Commit with conventional commit message
git add .
git commit -m "feat: add user authentication system"

# 6. Push to remote
git push origin feature/your-feature-name

# 7. Create Pull Request on GitHub
```

### Running Tests

**Backend tests:**
```bash
cd backend
make test                    # Run all tests
make test-coverage          # With coverage report
go test ./internal/services # Test specific package
```

**Frontend tests:**
```bash
cd frontend
npm test                    # Run all tests
npm run test:unit          # Unit tests only
npm run test:e2e           # E2E tests
```

### Database Migrations

**Create new migration:**
```bash
cd backend
make migration-create NAME=add_users_table

# Creates:
# migrations/000002_add_users_table.up.sql
# migrations/000002_add_users_table.down.sql
```

**Apply migrations:**
```bash
make migrate-up             # Apply all pending migrations
make migrate-down           # Rollback last migration
make migrate-reset          # Rollback all, then apply all
```

## 🔧 Common Commands

### Backend (Makefile commands)
```bash
make dev                    # Start development server
make build                  # Build production binary
make test                   # Run tests
make lint                   # Run linter
make fmt                    # Format code
make clean                  # Clean build artifacts
make migrate-up             # Run migrations
make migrate-down           # Rollback migrations
```

### Frontend (npm scripts)
```bash
npm run dev                 # Start dev server
npm run build               # Build for production
npm run preview             # Preview production build
npm test                    # Run tests
npm run lint                # Run ESLint
npm run format              # Run Prettier
```

### Docker Commands
```bash
docker-compose up           # Start all services
docker-compose up -d        # Start in background
docker-compose down         # Stop all services
docker-compose ps           # List running services
docker-compose logs -f      # View logs (follow)
docker-compose exec backend sh   # Shell into backend container
```

## 📚 Documentation

- [System Architecture](docs/architecture/overview.md)
- [API Reference](docs/api/reference.md)
- [Database Schema](docs/architecture/database-schema.md)
- [Development Guide](docs/setup/development.md)
- [Deployment Guide](docs/deployment/production.md)
- [Architecture Decisions](docs/adr/)

## 🛡️ Security

- **Data Isolation:** PostgreSQL Row-Level Security (RLS)
- **Authentication:** JWT-based with refresh tokens
- **Password Hashing:** bcrypt with cost factor 12
- **HTTPS Only:** TLS 1.3 in production
- **Rate Limiting:** Per-IP and per-user limits
- **Input Validation:** Server-side validation on all inputs
- **SQL Injection Protection:** Parameterized queries only

## 🧪 Testing

### Test Coverage Goals

- Backend: > 80% code coverage
- Frontend: > 70% code coverage
- Critical paths: 100% coverage

### Test Types

1. **Unit Tests:** Test individual functions
2. **Integration Tests:** Test component interactions
3. **E2E Tests:** Test complete user flows
4. **Performance Tests:** Load testing with k6

## 🚢 Deployment

### Development
```bash
# Local development with hot reload
make dev (backend)
npm run dev (frontend)
```

### Staging
```bash
# Deploy to staging environment
./scripts/deploy-staging.sh
```

### Production
```bash
# Deploy to production (requires approvals)
./scripts/deploy-production.sh
```

## 🐛 Troubleshooting

### Backend won't start

**Error: "database connection failed"**
```bash
# Check PostgreSQL is running
docker ps | grep postgres

# Check connection string in .env
cat backend/.env | grep DB_

# Test connection manually
psql -h localhost -U aurganize -d aurganize_v62
```

### Frontend build fails

**Error: "node_modules not found"**
```bash
# Delete and reinstall dependencies
rm -rf frontend/node_modules
cd frontend && npm install
```

### Port already in use

**Error: "address already in use"**
```bash
# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>
```

## 👥 Team

- **Developer 1:** Backend (Go/PostgreSQL/API)
- **Developer 2:** Frontend (Svelte/TypeScript/UI)

## 📝 License

Proprietary - All Rights Reserved

## 🤝 Contributing

1. Fork the repository
2. Create feature branch (`feature/amazing-feature`)
3. Commit changes (`feat: add amazing feature`)
4. Push to branch
5. Create Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.


**Made with ❤️ by the Aurganize Team**
EOF