FireWatch

A real-time incident management platform for DevOps teams to track, respond to, and resolve infrastructure incidents.

---

Table of Contents

• Features
• Screenshots
• Tech Stack
• Prerequisites
• Installation
  • Database Setup
  • Backend Setup
  • Frontend Setup
• Usage
• API Reference
• Project Structure
• License

---

Features

• Incident Lifecycle Management - Track incidents from triggered → acknowledged → resolved
• Priority & Severitelcid@mail.comy Levels - Classify incidents (P1-P5, Critical/High/Medium/Low)
• Activity Timeline - Full audit trail of all incident actions
• Team Collaboration - Find teammates by company domain and message them
• On-Call Management - Toggle on-call status and see who's available
• XP & Leaderboard - Gamified incident response with points and rankings
• Real-Time Dashboard - Live metrics and incident counts
• JWT Authentication - Secure token-based authentication

---

Screenshots

Landing Page

The public landing page showcasing FireWatch features.

Dashboard

Main dashboard showing incident metrics, leaderboard, and incident list.

Incident Details

View incident details, timeline, notes, and update status.

Team Directory

Find and message teammates from your organization.

Messaging

Direct messaging between team members.

Login

Secure authentication with JWT tokens.

---

Tech Stack

Component	Technology
Backend	Python, FastAPI
Frontend	React, Vite
Styling	Tailwind CSS
Database	PostgreSQL
ORM	SQLAlchemy
Migrations	Alembic
Authentication	JWT, OAuth2, bcrypt
Validation	Pydantic

---

Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.10 or higher
• Node.js 18 or higher
• PostgreSQL 14 or higher
• Git

---

Installation

1. Database Setup

Create a PostgreSQL database for the project:

# Login to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE firewatch;

# Create user (optional)
CREATE USER firewatch_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE firewatch TO firewatch_user;

# Exit
\q

2. Backend Setup

Clone the repository and set up the Python environment:

# Clone the repository
git clone https://github.com/YOUR_USERNAME/firewatch.git
cd firewatch

# Create virtual environment
python -m venv venv
elcid@mail.com
# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Create the environment file:

# Copy example env file
cp .env.example .env

Edit .env with your configuration:

DATABASE_URL=postgresql://postgres:your_password@localhost/firewatch
SECRET_KEY=your-secret-key-here
ALGO=HS256
TOKEN_TIME_IN_MINUTES=60

Generate a secure secret key:

openssl rand -hex 32

Run database migrations:

alembic upgrade head

Start the backend server:

uvicorn app.main:app --reload

The API will be available at: http://localhost:8000

API documentation at: http://localhost:8000/docs

3. Frontend Setup

Open a new terminal and navigate to the frontend directory:

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

The frontend will be available at: http://localhost:5173

---

Usage

1. Register an Account

Navigate to http://localhost:5173/register and create a new account.

2. Login

Login with your credentials at http://localhost:5173/login.

3. Create an Incident

From the dashboard, click "New Incident" to report a new incident.

Fill in the details:

• Title - Brief description of the issue
• Service - Affected service name
• Description - Detailed explanation
• Severity - Critical, High, Medium, or Low
• Priority - P1 (highest) to P5 (lowest)

4. Manage Incidents

Click on any incident card to view details, add notes, or update status.

Status Workflow:

• Triggered → Click "Acknowledge" to claim the incident
• Acknowledged → Click "Resolve" when the issue is fixed
• Add notes to document your investigation

5. View Team Members

Click the "Team" button in the header to view teammates from your organization.

Team members are automatically grouped by email domain (e.g., all @company.com users see each other).

6. Send Messages

Click "Message" on any team member to start a conversation.

7. Toggle On-Call Status

Click the "On-Call" / "Off-Duty" button in the header to toggle your availability.

8. Earn XP

Earn XP by responding to incidents:

Action	XP Earned
Report an incident	+5 XP
Acknowledge an incident	+10 XP
Resolve a Low severity incident	+10 XP
Resolve a Medium severity incident	+25 XP
Resolve a High severity incident	+50 XP
Resolve a Critical severity incident	+100 XP
Add a note to an incident	+2 XP

View the leaderboard on the dashboard to see top responders.

---

API Reference

Authentication

Method	Endpoint	Description
POST	/login	Get JWT access token
POST	/users/	Register new user
GET	/users/me	Get current user profile

Incidents

Method	Endpoint	Description
GET	/incidents/	List all incidents
POST	/incidents/	Create new incident
GET	/incidents/{id}	Get incident details
PUT	/incidents/{id}	Update incident
PATCH	/incidents/{id}/status	Update status (acknowledge/resolve)
POST	/incidents/{id}/notes	Add note to incident
DELETE	/incidents/{id}	Delete incident
GET	/incidents/metrics	Get incident metrics
GET	/incidents/leaderboard	Get XP leaderboard

Team & Messaging

Method	Endpoint	Description
GET	/users/team	List team members
GET	/users/on-call	List on-call engineers
PATCH	/users/me/on-call	Toggle on-call status
POST	/messages/	Send a message
GET	/messages/conversations	List conversations
GET	/messages/{user_id}	Get conversation with user
GET	/messages/unread/count	Get unread message count

Services

Method	Endpoint	Description
GET	/services/	List all services
POST	/services/	Register new service
PATCH	/services/{id}/status	Update service status

---

Project Structure

firewatch/
├── app/
│   ├── main.py              # FastAPI application entry
│   ├── config.py            # Environment configuration
│   ├── database.py          # Database connection
│   ├── models.py            # SQLAlchemy models
│   ├── schemas.py           # Pydantic schemas
│   ├── security.py          # JWT & password hashing
│   └── routes/
│       ├── auth.py          # Authentication endpoints
│       ├── user.py          # User management
│       ├── incident.py      # Incident CRUD & status
│       ├── message.py       # Direct messaging
│       ├── service.py       # Service registry
│       └── ack.py           # Acknowledgments
├── alembic/
│   ├── env.py               # Migration configuration
│   └── versions/            # Migration files
├── frontend/
│   ├── src/
│   │   ├── components/      # React components
│   │   ├── context/         # Auth context
│   │   ├── pages/           # Page components
│   │   │   ├── Landing.jsx
│   │   │   ├── Login.jsx
│   │   │   ├── Register.jsx
│   │   │   ├── Dashboard.jsx
│   │   │   └── Team.jsx
│   │   ├── services/        # API client
│   │   ├── App.jsx
│   │   └── main.jsx
│   ├── package.json
│   └── vite.config.js
├── screenshots/             # README screenshots
├── requirements.txt         # Python dependencies
├── alembic.ini             # Alembic configuration
├── .env.example            # Environment template
└── README.md

---