From 7f7ea3fef4db4af922fc760e8b49ff6225d8da37 Mon Sep 17 00:00:00 2001 From: Keith Smith Date: Thu, 18 Dec 2025 17:44:10 -0700 Subject: [PATCH] Add comprehensive README.md documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added detailed documentation covering: - Feature overview and capabilities - Installation and quick start guide - Configuration options and environment setup - API documentation and endpoints - Project structure explanation - Docker deployment instructions - Database model descriptions - Development guidelines - Production deployment checklist - Mobile app integration details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- README.md | 348 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b34a10f --- /dev/null +++ b/README.md @@ -0,0 +1,348 @@ +# 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 +``` + +### 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 +- `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 +``` + +### 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