KeepItGoingServer/README.md

# KeepItGoing Server

A powerful Django-based task management system with time tracking, tag organization, and real-time collaboration features.

## Features

### Task Management
- **Hierarchical Tasks**: Support for parent tasks and subtasks
- **Priority Levels**: Low, Medium, High, and Urgent
- **Status Tracking**: Pending, In Progress, Completed, Cancelled
- **Due Dates & Times**: Set specific due dates and times for tasks
- **Recurrence**: Daily, Weekly, Bi-weekly, Monthly, Yearly, and Custom patterns

### Organization
- **Tag-Based System**: Organize tasks with multiple colored tags
- **Smart Filtering**: View tasks by All, Today, Upcoming, Overdue, or Completed
- **Auto-Tag Assignment**: New tasks automatically inherit the active filter tag
- **Flexible Sorting**: Sort by due date (earliest/latest) or priority (high-to-low/low-to-high)

### Time Tracking
- **Start/Stop Timers**: Built-in time tracking for tasks
- **Time Entry History**: View detailed time logs for each task
- **Formatted Display**: Time shown as H:MM:SS with visual indicators
- **Running Timer Display**: Always visible timer in the UI when tracking time

### Collaboration
- **Task Sharing**: Share individual tasks or entire tags with other users
- **Multi-user Support**: Full authentication and user management
- **Shared Views**: See tasks shared with you alongside your own

### User Interface
- **3-Pane Layout**: Sidebar navigation, task list, and detail panel
- **Responsive Design**: Works on desktop, tablet, and mobile
- **Dark Mode**: Built-in dark/light theme toggle
- **Quick Add**: Fast task creation from any filter view
- **Inline Actions**: Toggle completion, start/stop timers without leaving the list

### API & Sync
- **RESTful API**: Full REST API for programmatic access
- **Mobile App Support**: Sync protocol for Android app
- **Real-time Updates**: Task changes sync across devices
- **Conflict Resolution**: Handles offline changes and syncing

## Tech Stack

- **Backend**: Django 5.x, Django REST Framework
- **Database**: SQLite (development), PostgreSQL-compatible
- **Task Queue**: Celery with Redis
- **Authentication**: JWT tokens with session support
- **Frontend**: HTML5, CSS3, Vanilla JavaScript
- **Deployment**: Docker support included

## Installation

### Prerequisites
- Python 3.12+
- pip
- virtualenv (recommended)

### Quick Start

1. **Clone the repository**
   ```bash
   git clone https://git.firebugit.com/Firebug_IT/KeepItGoingServer.git
   cd KeepItGoingServer
   ```

2. **Create virtual environment**
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure environment**
   ```bash
   cp .env.example .env
   # Edit .env with your settings
   ```

5. **Run migrations**
   ```bash
   export DJANGO_SETTINGS_MODULE=config.settings.development
   python manage.py migrate
   ```

6. **Create superuser**
   ```bash
   python manage.py createsuperuser
   ```

7. **Run development server**
   ```bash
   python manage.py runserver
   ```

8. **Access the application**
   - Web Interface: http://localhost:8000
   - Admin Panel: http://localhost:8000/admin
   - API Root: http://localhost:8000/api/

## Configuration

### Settings Modules

The project uses different settings modules for different environments:

- `config.settings.development` - Local development
- `config.settings.production` - Production deployment
- `config.settings.selfhosted` - Self-hosted instances

Set via environment variable:
```bash
export DJANGO_SETTINGS_MODULE=config.settings.development
```

### Database Configuration

The application supports multiple database backends. Choose the one that fits your needs.

#### SQLite3 (Default - Development)

SQLite3 is the default database and requires no additional setup. It's perfect for development and single-user scenarios.

**Configuration in `config/settings/development.py`:**
```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}
```

**Pros:**
- Zero configuration
- No separate database server needed
- Perfect for development and testing

**Cons:**
- Not recommended for production with multiple users
- Limited concurrent write operations
- No network access (local file only)

#### PostgreSQL (Recommended for Production)

PostgreSQL is the recommended database for production deployments.

**1. Install PostgreSQL:**
```bash
# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib libpq-dev

# macOS
brew install postgresql
```

**2. Create database and user:**
```bash
sudo -u postgres psql
CREATE DATABASE keepitgoing;
CREATE USER keepitgoing_user WITH PASSWORD 'your_secure_password';
ALTER ROLE keepitgoing_user SET client_encoding TO 'utf8';
ALTER ROLE keepitgoing_user SET default_transaction_isolation TO 'read committed';
ALTER ROLE keepitgoing_user SET timezone TO 'UTC';
GRANT ALL PRIVILEGES ON DATABASE keepitgoing TO keepitgoing_user;
\q
```

**3. Install Python driver:**
```bash
pip install psycopg2-binary
```

**4. Update settings:**

Add to your `.env` file:
```bash
DATABASE_URL=postgresql://keepitgoing_user:your_secure_password@localhost:5432/keepitgoing
```

Or configure directly in settings:
```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'keepitgoing',
        'USER': 'keepitgoing_user',
        'PASSWORD': 'your_secure_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}
```

**5. Run migrations:**
```bash
python manage.py migrate
```

#### MariaDB/MySQL

MariaDB and MySQL are also supported for production use.

**1. Install MariaDB:**
```bash
# Ubuntu/Debian
sudo apt-get install mariadb-server libmariadb-dev

# macOS
brew install mariadb
```

**2. Create database and user:**
```bash
sudo mysql
CREATE DATABASE keepitgoing CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'keepitgoing_user'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON keepitgoing.* TO 'keepitgoing_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

**3. Install Python driver:**
```bash
pip install mysqlclient
```

**4. Update settings:**

Add to your `.env` file:
```bash
DATABASE_URL=mysql://keepitgoing_user:your_secure_password@localhost:3306/keepitgoing
```

Or configure directly in settings:
```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'keepitgoing',
        'USER': 'keepitgoing_user',
        'PASSWORD': 'your_secure_password',
        'HOST': 'localhost',
        'PORT': '3306',
        'OPTIONS': {
            'charset': 'utf8mb4',
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        },
    }
}
```

**5. Run migrations:**
```bash
python manage.py migrate
```

#### Database Migration Between Backends

To migrate data from one database to another:

**1. Export data from current database:**
```bash
python manage.py dumpdata --natural-foreign --natural-primary \
    -e contenttypes -e auth.Permission --indent 4 > data.json
```

**2. Update database settings to new backend**

**3. Run migrations on new database:**
```bash
python manage.py migrate --run-syncdb
```

**4. Import data:**
```bash
python manage.py loaddata data.json
```

### Environment Variables

Key environment variables (see `.env.example`):

- `SECRET_KEY` - Django secret key (required in production)
- `DEBUG` - Enable debug mode (True/False)
- `ALLOWED_HOSTS` - Comma-separated list of allowed hosts
- `DATABASE_URL` - Database connection string (optional, overrides settings)
- `REDIS_URL` - Redis connection for Celery
- `CSRF_TRUSTED_ORIGINS` - HTTPS origins for CSRF

## API Documentation

### Authentication

The API supports both session-based and token-based authentication.

**Get Token:**
```bash
POST /api/auth/login/
{
  "email": "user@example.com",
  "password": "password"
}
```

**Use Token:**
```bash
Authorization: Bearer <token>
```

### Endpoints

#### Tasks
- `GET /api/tasks/` - List all tasks
- `POST /api/tasks/` - Create task
- `GET /api/tasks/{id}/` - Get task details
- `PUT /api/tasks/{id}/` - Update task
- `DELETE /api/tasks/{id}/` - Delete task

#### Tags
- `GET /api/tags/` - List all tags
- `POST /api/tags/` - Create tag
- `GET /api/tags/{id}/` - Get tag details
- `PUT /api/tags/{id}/` - Update tag
- `DELETE /api/tags/{id}/` - Delete tag

#### Time Entries
- `GET /api/time-entries/` - List time entries
- `POST /api/time-entries/` - Create time entry
- `POST /api/tasks/{id}/start-timer/` - Start timer
- `POST /api/time-entries/{id}/stop/` - Stop timer

#### Sync (Mobile)
- `POST /api/sync/sync/` - Bidirectional sync endpoint

## Project Structure

```
keepitgoing-server/
├── config/              # Project configuration
│   ├── settings/        # Environment-specific settings
│   ├── urls.py          # Main URL configuration
│   └── wsgi.py          # WSGI entry point
├── tasks/               # Task management app
│   ├── models.py        # Task, Tag, TimeEntry models
│   ├── views.py         # API and web views
│   ├── serializers.py   # DRF serializers
│   └── migrations/      # Database migrations
├── users/               # User management app
├── sync/                # Mobile sync app
├── notifications/       # Notification system
├── templates/           # Django templates
│   ├── base.html        # Base template
│   └── tasks/           # Task templates
├── static/              # Static files
│   ├── css/             # Stylesheets
│   └── js/              # JavaScript
├── manage.py            # Django management script
└── requirements.txt     # Python dependencies
```

## Docker Deployment

### Development
```bash
docker-compose -f docker-compose.dev.yml up
```

### Production
```bash
docker-compose up -d
```

## Database Models

### Task
- Hierarchical structure (parent/subtasks)
- Multiple tags per task
- Due date and time
- Priority and status
- Recurrence patterns
- Soft delete support

### Tag
- Color-coded organization
- Multi-task assignment
- Sort ordering
- Archive capability

### TimeEntry
- Start/end timestamps
- Duration calculation
- User association

### TaskShare
- Share tasks or entire tags
- User-to-user sharing
- Permission management

## Development

### Running Tests
```bash
python manage.py test
```

### Creating Migrations
```bash
python manage.py makemigrations
```

### Collecting Static Files
```bash
python manage.py collectstatic
```

### Code Style
- Follow PEP 8 for Python code
- Use meaningful variable names
- Add docstrings to functions and classes

## Deployment

### Production Checklist

- [ ] Set `DEBUG = False`
- [ ] Configure strong `SECRET_KEY`
- [ ] Set up proper `ALLOWED_HOSTS`
- [ ] Configure `CSRF_TRUSTED_ORIGINS` for HTTPS
- [ ] Use PostgreSQL instead of SQLite
- [ ] Set up Redis for Celery
- [ ] Configure static file serving
- [ ] Set up SSL/TLS certificates
- [ ] Configure backup strategy
- [ ] Set up monitoring and logging

### Nginx Configuration

Example nginx config for reverse proxy:

```nginx
server {
    listen 443 ssl;
    server_name tasks.firebugit.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /path/to/static/;
    }
}
```

## Mobile App Integration

This server works with the KeepItGoing Android app via the sync endpoint.

**Sync Protocol:**
- Client sends current state and last sync timestamp
- Server returns updates since last sync
- Server accepts client changes
- Conflict resolution handled server-side

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

Proprietary - All Rights Reserved
Copyright (c) 2025 Firebug IT

## Support

For issues and questions:
- Create an issue in the repository
- Email: keith@firebugit.com

## Changelog

### Version 1.0.0 (2025-01-18)
- Initial release
- Complete task management system
- Tag-based organization
- Time tracking
- Multi-user support
- Mobile app sync
- Web interface with dark mode
- Responsive design
- RESTful API

---

Built with ❤️ by Firebug IT