Agile Alliance (AA) - Project Management Application

A full-stack web application for Agile project management with user authentication, sprint boards, story management, and customizable workflows.

Tech Stack

Frontend

• React 18 with TypeScript
• Vite (Build tool and dev server)
• TailwindCSS 3 (Styling)
• React Router 6 (SPA routing)
• Radix UI (Component library)

Backend

• Node.js with Express 5
• Prisma ORM 6
• PostgreSQL 15 (Database)
• Docker & Docker Compose

Development Tools

• PNPM 10+ (Package manager)
• TypeScript 5
• Vitest (Testing)
• Prettier (Code formatting)

---

Prerequisites

You'll need these installed before getting started:

1. Node.js (v18+) - Download here

   • Check: node --version

2. PNPM (v10+) - Fast package manager

   npm install -g pnpm
   pnpm --version  # verify

3. Docker Desktop - For the database

   • Download here
   • ⚠️ Must be running before you start the app
   • Check: docker --version

4. Git - Download here

   • Check: git --version

---

Setting up the Project Dependencies

1. Clone the Repository

git clone https://github.com/dgupta98/AAWebApp.git
cd AAWebApp

2. Install Dependencies

pnpm install

Takes 2-3 minutes. Ignore any WARN messages.

3. Make Scripts Executable (macOS/Linux only)

chmod +x scripts/start-all.sh scripts/stop-all.sh

4. Start Docker Desktop

Open Docker Desktop and wait for it to fully start (green icon).

---

5. Running the App Quick Start (One Command)

pnpm start:all

This automatically:

• Starts the database
• Runs migrations
• Launches the dev server
• Opens your browser to http://localhost:8080

Wait for "VITE ready" in your terminal, then you're good to go!

Stopping

pnpm stop:all

Other URLs:

• Frontend: http://localhost:8080
• Database GUI: http://localhost:5555 (Prisma Studio)

---

Troubleshooting

Docker not running? → Open Docker Desktop and wait for it to start

Port 5432 in use? (another database running)

lsof -ti:5432 | xargs kill -9  # or: brew services stop postgresql
pnpm db:down && pnpm db:up

Port 8080 in use?

lsof -ti:8080 | xargs kill -9
pnpm dev

Module errors?

rm -rf node_modules
pnpm install
pnpm prisma:generate

Database errors?

pnpm db:down
pnpm db:up
sleep 10
pnpm prisma:migrate

Permission denied? (macOS/Linux)

chmod +x scripts/*.sh

---

Useful Commands

Command	What it does
pnpm start:all	Start everything (recommended)
pnpm stop:all	Stop everything
pnpm dev	Dev server only
pnpm db:up / db:down	Start/stop database
pnpm prisma:studio	Open database GUI
pnpm typecheck	Check TypeScript
pnpm test	Run tests
pnpm build	Build for production

---

Project Structure

client/      # Frontend (React)
server/      # Backend (Express)
prisma/      # Database schema & migrations
shared/      # Shared types

---

Features

Authentication & User Management

• User registration and login
• Session-based authentication with HTTP-only cookies
• Password reset functionality

Project Management

• Create/delete projects with unique keys
• Role-based access control (Owner/Member)
• Project-scoped views and permissions
• Project statistics dashboard

Epic Management

• Group user stories into epics
• Link epics to projects
• Epic status tracking

User Story Management

• Full CRUD operations on user stories
• Customizable fields: title, description, priority, story points, assignee
• Archive/restore functionality
• Story comments with timestamps
• Project and epic assignment

Sprint Board

• Visual Kanban-style board
• Dynamic status columns (customizable)
• Drag-and-drop to update story status
• Real-time status persistence
• Project-scoped sprint views

Backlog Management

• Global product backlog
• Project-scoped backlog views
• Filter and search capabilities
• Priority and status indicators

Customizable Workflows

• Add, rename, and delete status labels
• Default statuses: TODO → IN_PROGRESS → READY_FOR_TEST → DONE
• Custom statuses appear before DONE
• Changes reflect across all views (board, forms, filters)

Dashboard & Analytics

• Real-time story and point metrics
• Recent activity feed
• Story status distribution charts

---

Database Schema

The application uses PostgreSQL with the following main models:

• User: Authentication and user profiles
• Session: Session management for authentication
• Project: Project organization
• ProjectMember: User-project relationships with roles
• Epic: Feature groupings within projects
• Story: User stories with full metadata
• Comment: Story comments
• StoryStatusLabel: Customizable status labels

For detailed schema, see prisma/schema.prisma.

---

Development Tips

Making changes:

• Frontend changes auto-reload (Vite hot reload)
• Backend changes need a restart (Ctrl+C then pnpm dev)
• Always run pnpm typecheck before committing

Database changes:

1. Edit prisma/schema.prisma
2. Run pnpm prisma:migrate
3. Name your migration when prompted

Adding features:

1. Create a feature branch
2. Make your changes
3. Run tests: pnpm test
4. Commit and push

---

Testing & Building

pnpm test              # Run tests
pnpm test --watch      # Watch mode
pnpm typecheck         # Type checking
pnpm build             # Production build
pnpm start             # Run production build

---

Known Limitations

• Email service not configured (password reset tokens shown in dev mode)
• Sprint planning and velocity tracking coming soon
• Real-time collaboration planned for future release

---