Files
project-managment/README.md
T
sankalp 75bccb4528 chore(root): lowercase "Recommended" to "recommended" and add createcachetable to justfile
Ensure consistent casing and include the necessary cache table creation in setup steps
2026-06-28 16:21:51 +05:45

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) |