Ensure consistent casing and include the necessary cache table creation in setup steps
184 lines
5.3 KiB
Markdown
184 lines
5.3 KiB
Markdown
# Project Management
|
|
|
|
A full-featured Django project management tool with Kanban boards, ticket tracking, epics, notifications, and external access sharing.
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend** — Django 6, Django REST Framework, JWT Auth
|
|
- **Frontend** — HTMX, Tailwind CSS v4 (via django-tailwind-cli)
|
|
- **Database** — SQLite (dev) / MySQL (prod)
|
|
- **Task Queue** — Django Q2
|
|
- **API Docs** — drf-spectacular (Swagger UI)
|
|
- **Package Manager** — [uv](https://github.com/astral-sh/uv)
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Projects** — create, manage, pin projects with colour labels and member roles
|
|
- **Tickets** — full CRUD, bulk ops, Excel import/export, priority and status management
|
|
- **Epics** — group tickets into epics with progress tracking
|
|
- **Kanban Board** — drag-and-drop ticket status columns per project
|
|
- **Notifications** — in-app and email notifications on ticket events
|
|
- **User Management** — role-based access (superadmin / manager / member)
|
|
- **External Access** — share a read-only dashboard link with external users via a token
|
|
- **Project Notes** — attach notes to projects
|
|
- **Google OAuth** — sign in with Google
|
|
- **Dark / Light Mode** — per-user UI preferences
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone & install
|
|
|
|
```bash
|
|
git clone https://github.com/S4NKALP/project-managment.git
|
|
cd project-managment
|
|
uv sync
|
|
```
|
|
|
|
### 2. Configure environment
|
|
|
|
```bash
|
|
cp .env.sample .env
|
|
# Edit .env with your values
|
|
```
|
|
|
|
Required `.env` keys:
|
|
|
|
```ini
|
|
DJANGO_SETTINGS_MODULE=config.settings.development
|
|
SECRET_KEY=your-secret-key
|
|
BASE_URL=http://localhost:8000
|
|
SITE_NAME=Project Management
|
|
|
|
# Google OAuth (optional)
|
|
GOOGLE_CLIENT_ID=
|
|
GOOGLE_CLIENT_SECRET=
|
|
GOOGLE_REDIRECT_URI=http://localhost:8000/api/auth/google/callback/
|
|
```
|
|
|
|
### 3. Run migrations & create superuser
|
|
|
|
```bash
|
|
uv run python manage.py migrate
|
|
uv run python manage.py createcachetable
|
|
uv run python manage.py createsuperuser
|
|
```
|
|
|
|
### 4. Start development server
|
|
|
|
```bash
|
|
uv run python manage.py runserver
|
|
```
|
|
|
|
Open **http://localhost:8000** in your browser (redirects to the dashboard automatically).
|
|
|
|
---
|
|
|
|
## Using `just` (recommended)
|
|
|
|
Install [just](https://github.com/casey/just), then:
|
|
|
|
```bash
|
|
just setup # install deps + migrate + createcachetable + createsuperuser
|
|
just dev # run dev server
|
|
just migrate # run migrations
|
|
just test # run tests
|
|
just lint # ruff lint
|
|
just format # ruff format
|
|
just ci # lint + format check + django check
|
|
```
|
|
|
|
Run `just` with no arguments to see all available commands.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
project-managment/
|
|
├── config/ # Django config package
|
|
│ ├── settings/
|
|
│ │ ├── base.py # Shared settings
|
|
│ │ ├── development.py # Dev overrides (SQLite)
|
|
│ │ └── production.py # Prod overrides (MySQL)
|
|
│ ├── urls.py # Root URL conf
|
|
│ ├── wsgi.py
|
|
│ └── asgi.py
|
|
│
|
|
├── src/ # Application code
|
|
│ ├── accounts/ # User model, auth, Google OAuth
|
|
│ ├── projects/ # Projects & members (API)
|
|
│ ├── tickets/ # Tickets, statuses, priorities (API)
|
|
│ ├── epics/ # Epics
|
|
│ ├── notes/ # Project notes
|
|
│ ├── notifications/ # In-app & email notifications
|
|
│ ├── external/ # External token-based access
|
|
│ └── dashboard/ # All HTML-rendering views
|
|
│ ├── views/ # Dashboard widgets & charts
|
|
│ ├── list_views/ # Project/ticket list views
|
|
│ ├── page_views/ # CRUD page views
|
|
│ ├── board_views/ # Kanban board views
|
|
│ └── context_processors.py
|
|
│
|
|
├── templates/ # Jinja/Django HTML templates
|
|
├── static/ # Static files (CSS, JS)
|
|
├── manage.py
|
|
├── pyproject.toml # Dependencies & ruff config
|
|
├── justfile # Task runner shortcuts
|
|
├── Dockerfile
|
|
├── Procfile
|
|
└── .env.sample
|
|
```
|
|
|
|
---
|
|
|
|
## API Documentation
|
|
|
|
Running in development mode:
|
|
|
|
| Endpoint | Description |
|
|
|---|---|
|
|
| `http://localhost:8000/api/docs/` | Swagger UI |
|
|
| `http://localhost:8000/api/schema/` | OpenAPI schema |
|
|
|
|
### Key API routes
|
|
|
|
| Method | Endpoint | Description |
|
|
|---|---|---|
|
|
| `POST` | `/api/auth/login/` | JWT login |
|
|
| `POST` | `/api/auth/token/refresh/` | Refresh token |
|
|
| `GET/POST` | `/api/projects/` | List / create projects |
|
|
| `GET/POST` | `/api/tickets/` | List / create tickets |
|
|
| `GET/POST` | `/api/notifications/` | Notifications |
|
|
|
|
---
|
|
|
|
## CI / CD
|
|
|
|
GitHub Actions workflow (`.github/workflows/ci.yml`) runs three jobs on every push/PR to `main` and `develop`:
|
|
|
|
| Job | Steps |
|
|
|---|---|
|
|
| **Lint** | `ruff check` + `ruff format --check` |
|
|
| **Test** | Django system check → migration check → `manage.py test` |
|
|
| **Security** | `manage.py check --deploy` |
|
|
|
|
---
|
|
|
|
## Environment Variables Reference
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `DJANGO_SETTINGS_MODULE` | — | `config.settings.development` or `production` |
|
|
| `SECRET_KEY` | — | Django secret key |
|
|
| `BASE_URL` | `http://localhost:8000` | Used for email links |
|
|
| `SITE_NAME` | `Project Management` | Displayed in UI & emails |
|
|
| `GOOGLE_CLIENT_ID` | `""` | Google OAuth client ID |
|
|
| `GOOGLE_CLIENT_SECRET` | `""` | Google OAuth secret |
|
|
| `GOOGLE_REDIRECT_URI` | — | OAuth callback URL |
|
|
| `DB_NAME / DB_USER / DB_PASSWORD / DB_HOST / DB_PORT` | — | MySQL (production only) |
|
|
| `EMAIL_HOST / EMAIL_PORT / EMAIL_HOST_USER / EMAIL_HOST_PASSWORD` | — | SMTP (production only) |
|
|
| `FRONTEND_URL` | — | Allowed CORS origin (production) | |