sankalp
9d5ebcfcde
Add Kanban board, epics, notifications, external sharing, and related API endpoints; update README and install required packages such as django‑q2, openpyxl, and others.
183 lines
5.2 KiB
Markdown
183 lines
5.2 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 & status management
|
||
- ️ **Epics** — group tickets into epics with progress tracking
|
||
- ️ **Kanban Board** — drag-and-drop ticket status columns per project
|
||
- **Notifications** — in-app + 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 createsuperuser
|
||
```
|
||
|
||
### 4. Start development server
|
||
|
||
```bash
|
||
uv run python manage.py runserver
|
||
```
|
||
|
||
Visit **http://localhost:8000** → redirects to the dashboard automatically.
|
||
|
||
---
|
||
|
||
## Using `just` (Recommended)
|
||
|
||
Install [just](https://github.com/casey/just), then:
|
||
|
||
```bash
|
||
just setup # install deps + migrate + 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) | |