Skip to content

README.md

Latest commit

 

History

History
364 lines (258 loc) · 9.01 KB

README.md

File metadata and controls

364 lines (258 loc) · 9.01 KB
Raw

FireWatch

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

FireWatch Landing Page

Table of Contents

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.

Landing Page

Dashboard

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

Dashboard

Incident Details

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

Incident Details

Team Directory

Find and message teammates from your organization.

Team Page

Messaging

Direct messaging between team members.

Messaging

Login

Secure authentication with JWT tokens.

Login

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.

Register

2. Login

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

Login

3. Create an Incident

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

Create 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.

Incident Details

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 Page

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.

Messaging

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