docs: Reorganize project documentation
- Remove outdated documentation files - Add ARCHITECTURE.md and BACKLOG.md - Add docs/ folder - Update CURRENT-STATE.md Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
chihlasm
405
ARCHITECTURE.md
Normal file
405
ARCHITECTURE.md
Normal file
@@ -0,0 +1,405 @@
|
|||||||
|
# Patherly - Architecture & Overview
|
||||||
|
|
||||||
|
> **Purpose:** Core technical reference combining project vision and technical implementation.
|
||||||
|
> **Last Updated:** February 2, 2026
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Project Vision](#project-vision)
|
||||||
|
2. [Problem Statement](#problem-statement)
|
||||||
|
3. [Solution Overview](#solution-overview)
|
||||||
|
4. [Tech Stack](#tech-stack)
|
||||||
|
5. [System Architecture](#system-architecture)
|
||||||
|
6. [Database Schema](#database-schema)
|
||||||
|
7. [API Endpoints](#api-endpoints)
|
||||||
|
8. [Data Structures](#data-structures)
|
||||||
|
9. [Security](#security)
|
||||||
|
10. [Deployment](#deployment)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Project Vision
|
||||||
|
|
||||||
|
A decision tree troubleshooting application designed for MSP engineers to transform diagnostic processes into clean, professional documentation automatically.
|
||||||
|
|
||||||
|
**Tagline:** "Take the path MOST traveled"
|
||||||
|
|
||||||
|
### Success Criteria
|
||||||
|
|
||||||
|
**3-Month Goal:** Michael uses this tool for 50% of his tickets
|
||||||
|
|
||||||
|
**Key Metrics:**
|
||||||
|
- Time saved per ticket
|
||||||
|
- Documentation quality improvement
|
||||||
|
- Reduction in "what did I do?" moments
|
||||||
|
- Team adoption rate
|
||||||
|
|
||||||
|
### Target Users
|
||||||
|
|
||||||
|
**Primary:** Senior Systems Engineers at MSPs managing Windows Server, Active Directory, Citrix, networking equipment
|
||||||
|
|
||||||
|
**Secondary:**
|
||||||
|
- Junior engineers needing guided troubleshooting
|
||||||
|
- Onsite technicians following remote engineer instructions
|
||||||
|
- MSP teams wanting standardized procedures
|
||||||
|
|
||||||
|
### Key Differentiators
|
||||||
|
|
||||||
|
1. **Automatic documentation generation** - No separate note-taking step
|
||||||
|
2. **On-the-fly customization** - Add custom branches when encountering edge cases
|
||||||
|
3. **Learning system** - Tracks common paths, suggests optimizations
|
||||||
|
4. **Automation integration** - Execute PowerShell/scripts directly from decision nodes
|
||||||
|
5. **Knowledge hub** - Links to documentation, KB articles, tutorials at each step
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
MSP engineers face constant context switching between diverse technical issues (file shares, server outages, VPN failures, Active Directory problems). Each context switch:
|
||||||
|
|
||||||
|
- Takes 15-25 minutes to regain full focus
|
||||||
|
- Creates cognitive overhead and attention residue
|
||||||
|
- Contributes to burnout (research-backed)
|
||||||
|
- Makes consistent documentation challenging
|
||||||
|
- Results in lost tribal knowledge
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Solution Overview
|
||||||
|
|
||||||
|
An intelligent decision tree system that:
|
||||||
|
|
||||||
|
- Guides engineers through proven troubleshooting paths
|
||||||
|
- Captures decisions and notes automatically
|
||||||
|
- Generates professional ticket documentation
|
||||||
|
- Builds institutional knowledge
|
||||||
|
- Reduces cognitive load during high-stress situations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
| Component | Technology |
|
||||||
|
|-----------|------------|
|
||||||
|
| Framework | React 18 + Vite + TypeScript |
|
||||||
|
| Styling | Tailwind CSS |
|
||||||
|
| State Management | Zustand (with immer + zundo) |
|
||||||
|
| Routing | React Router v6 |
|
||||||
|
| API Client | Axios |
|
||||||
|
| Offline | Service Workers + IndexedDB (planned) |
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
| Component | Technology |
|
||||||
|
|-----------|------------|
|
||||||
|
| Framework | Python FastAPI |
|
||||||
|
| ORM | SQLAlchemy 2.0 (async) |
|
||||||
|
| Validation | Pydantic |
|
||||||
|
| Auth | JWT (python-jose) + bcrypt |
|
||||||
|
| Migrations | Alembic |
|
||||||
|
|
||||||
|
### Database & Storage
|
||||||
|
| Component | Technology |
|
||||||
|
|-----------|------------|
|
||||||
|
| Database | PostgreSQL 16 |
|
||||||
|
| File Storage | S3-compatible (planned) |
|
||||||
|
| Development | Docker containers |
|
||||||
|
|
||||||
|
### Hosting
|
||||||
|
| Environment | Platform |
|
||||||
|
|-------------|----------|
|
||||||
|
| Development | Local (Vite + Uvicorn + Docker PostgreSQL) |
|
||||||
|
| Production | Railway Pro |
|
||||||
|
| Domain | patherly.com (api.patherly.com for backend) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## System Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ Frontend (React) │
|
||||||
|
│ - Tree Navigation UI │
|
||||||
|
│ - Tree Editor │
|
||||||
|
│ - Session Management │
|
||||||
|
│ - Export Functionality │
|
||||||
|
└─────────────────┬───────────────────────────────────┘
|
||||||
|
│ REST API (JSON)
|
||||||
|
┌─────────────────┴───────────────────────────────────┐
|
||||||
|
│ Backend (Python FastAPI) │
|
||||||
|
│ - Authentication & Authorization │
|
||||||
|
│ - Tree CRUD Operations │
|
||||||
|
│ - Session Tracking │
|
||||||
|
│ - Export Generation │
|
||||||
|
│ - File Upload/Storage (planned) │
|
||||||
|
└─────────────────┬───────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌─────────────────┴───────────────────────────────────┐
|
||||||
|
│ Database (PostgreSQL) │
|
||||||
|
│ - Trees (JSONB structure) │
|
||||||
|
│ - Sessions (path tracking) │
|
||||||
|
│ - Users & Teams │
|
||||||
|
│ - Attachments Metadata │
|
||||||
|
└──────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
### Users Table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE users (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
email VARCHAR(255) UNIQUE NOT NULL,
|
||||||
|
password_hash VARCHAR(255) NOT NULL,
|
||||||
|
name VARCHAR(255) NOT NULL,
|
||||||
|
role VARCHAR(50) NOT NULL DEFAULT 'engineer', -- admin, engineer, viewer
|
||||||
|
team_id UUID REFERENCES teams(id),
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||||
|
last_login TIMESTAMP WITH TIME ZONE
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Teams Table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE teams (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name VARCHAR(255) NOT NULL,
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Trees Table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE trees (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
name VARCHAR(255) NOT NULL,
|
||||||
|
description TEXT,
|
||||||
|
category VARCHAR(100),
|
||||||
|
tree_structure JSONB NOT NULL,
|
||||||
|
author_id UUID REFERENCES users(id),
|
||||||
|
team_id UUID REFERENCES teams(id),
|
||||||
|
is_active BOOLEAN DEFAULT true,
|
||||||
|
version INTEGER DEFAULT 1,
|
||||||
|
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||||
|
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||||
|
usage_count INTEGER DEFAULT 0
|
||||||
|
);
|
||||||
|
|
||||||
|
CREATE INDEX idx_trees_category ON trees(category);
|
||||||
|
CREATE INDEX idx_trees_search ON trees USING gin(to_tsvector('english', name || ' ' || description));
|
||||||
|
```
|
||||||
|
|
||||||
|
### Sessions Table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE sessions (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
tree_id UUID REFERENCES trees(id),
|
||||||
|
user_id UUID REFERENCES users(id),
|
||||||
|
tree_snapshot JSONB NOT NULL,
|
||||||
|
path_taken JSONB NOT NULL,
|
||||||
|
decisions JSONB NOT NULL,
|
||||||
|
started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
|
||||||
|
completed_at TIMESTAMP WITH TIME ZONE,
|
||||||
|
ticket_number VARCHAR(100),
|
||||||
|
client_name VARCHAR(255),
|
||||||
|
exported BOOLEAN DEFAULT false
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Attachments Table
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE attachments (
|
||||||
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
||||||
|
session_id UUID REFERENCES sessions(id),
|
||||||
|
node_id VARCHAR(100),
|
||||||
|
file_name VARCHAR(255) NOT NULL,
|
||||||
|
file_type VARCHAR(50),
|
||||||
|
file_size INTEGER,
|
||||||
|
storage_path VARCHAR(500),
|
||||||
|
uploaded_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| POST | `/api/v1/auth/register` | Register new user |
|
||||||
|
| POST | `/api/v1/auth/login` | Login (form data) |
|
||||||
|
| POST | `/api/v1/auth/login/json` | Login (JSON body) |
|
||||||
|
| POST | `/api/v1/auth/refresh` | Refresh access token |
|
||||||
|
| GET | `/api/v1/auth/me` | Get current user |
|
||||||
|
| POST | `/api/v1/auth/logout` | Logout |
|
||||||
|
|
||||||
|
### Trees
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/v1/trees` | List trees (paginated) |
|
||||||
|
| POST | `/api/v1/trees` | Create tree |
|
||||||
|
| GET | `/api/v1/trees/categories` | Get unique categories |
|
||||||
|
| GET | `/api/v1/trees/search` | Full-text search |
|
||||||
|
| GET | `/api/v1/trees/{id}` | Get tree by ID |
|
||||||
|
| PUT | `/api/v1/trees/{id}` | Update tree |
|
||||||
|
| DELETE | `/api/v1/trees/{id}` | Soft delete tree |
|
||||||
|
|
||||||
|
### Sessions
|
||||||
|
| Method | Endpoint | Description |
|
||||||
|
|--------|----------|-------------|
|
||||||
|
| GET | `/api/v1/sessions` | List user's sessions |
|
||||||
|
| POST | `/api/v1/sessions` | Start new session |
|
||||||
|
| GET | `/api/v1/sessions/{id}` | Get session |
|
||||||
|
| PUT | `/api/v1/sessions/{id}` | Update session |
|
||||||
|
| POST | `/api/v1/sessions/{id}/complete` | Mark complete |
|
||||||
|
| POST | `/api/v1/sessions/{id}/export` | Export (md/txt/html) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Structures
|
||||||
|
|
||||||
|
### Tree Structure (JSONB)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"id": "root",
|
||||||
|
"type": "decision",
|
||||||
|
"question": "Can you ping the server?",
|
||||||
|
"help_text": "Run: ping servername",
|
||||||
|
"options": [
|
||||||
|
{ "label": "Yes", "value": "yes", "next_node_id": "node_2" },
|
||||||
|
{ "label": "No", "value": "no", "next_node_id": "node_network" }
|
||||||
|
],
|
||||||
|
"children": [
|
||||||
|
{
|
||||||
|
"id": "node_2",
|
||||||
|
"type": "action",
|
||||||
|
"title": "Check service status",
|
||||||
|
"description": "Verify the service is running",
|
||||||
|
"commands": ["Get-Service -Name 'ServiceName'"],
|
||||||
|
"next_node_id": "node_3"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "node_3",
|
||||||
|
"type": "solution",
|
||||||
|
"title": "Issue Resolved",
|
||||||
|
"description": "Service restarted successfully",
|
||||||
|
"resolution_steps": ["Document the fix", "Update ticket"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Session Decision (JSONB array item)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"node_id": "node_1",
|
||||||
|
"question": "Can you ping the VDA?",
|
||||||
|
"answer": "yes",
|
||||||
|
"notes": "Ping successful, 2ms response time",
|
||||||
|
"timestamp": "2026-01-22T14:31:00Z",
|
||||||
|
"attachments": []
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
- JWT tokens: 15-minute access, 7-day refresh
|
||||||
|
- Passwords: bcrypt with cost factor 12
|
||||||
|
- Role-based access: admin, engineer, viewer
|
||||||
|
|
||||||
|
### API Security
|
||||||
|
- CORS configured for frontend origins
|
||||||
|
- Rate limiting planned
|
||||||
|
- Input validation via Pydantic
|
||||||
|
- SQL injection prevention via SQLAlchemy ORM
|
||||||
|
|
||||||
|
### Data Protection
|
||||||
|
- HTTPS in production
|
||||||
|
- Timezone-aware timestamps (UTC storage)
|
||||||
|
- Soft deletes for trees (is_active flag)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
### Development Setup
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# Terminal 1: Database
|
||||||
|
docker start patherly_postgres
|
||||||
|
|
||||||
|
# Terminal 2: Backend
|
||||||
|
cd backend
|
||||||
|
.\venv\Scripts\activate
|
||||||
|
uvicorn app.main:app --reload
|
||||||
|
|
||||||
|
# Terminal 3: Frontend
|
||||||
|
cd frontend
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Production (Railway)
|
||||||
|
|
||||||
|
- **Database:** Railway managed PostgreSQL
|
||||||
|
- **Backend:** api.patherly.com
|
||||||
|
- **Frontend:** patherly.com
|
||||||
|
- **Environment:** PR environments for testing
|
||||||
|
|
||||||
|
### Key Configuration
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Backend .env
|
||||||
|
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/patherly
|
||||||
|
SECRET_KEY=your-secret-key
|
||||||
|
ALGORITHM=HS256
|
||||||
|
ACCESS_TOKEN_EXPIRE_MINUTES=15
|
||||||
|
|
||||||
|
# Frontend .env
|
||||||
|
VITE_API_URL=http://localhost:8000
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
patherly/
|
||||||
|
├── backend/
|
||||||
|
│ ├── app/
|
||||||
|
│ │ ├── api/v1/endpoints/ # Route handlers
|
||||||
|
│ │ ├── core/ # Config, security, logging
|
||||||
|
│ │ ├── models/ # SQLAlchemy models
|
||||||
|
│ │ └── schemas/ # Pydantic schemas
|
||||||
|
│ ├── alembic/ # Migrations
|
||||||
|
│ ├── tests/ # pytest tests
|
||||||
|
│ └── scripts/ # Seed scripts
|
||||||
|
├── frontend/
|
||||||
|
│ ├── src/
|
||||||
|
│ │ ├── api/ # API client
|
||||||
|
│ │ ├── components/ # React components
|
||||||
|
│ │ ├── pages/ # Page components
|
||||||
|
│ │ └── store/ # Zustand stores
|
||||||
|
│ └── public/
|
||||||
|
└── docs/ # Documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*For current project status, see [CURRENT-STATE.md](./CURRENT-STATE.md)*
|
||||||
|
*For development setup, see [QUICK-START.md](./QUICK-START.md)*
|
||||||
|
*For known issues, see [LESSONS-LEARNED.md](./LESSONS-LEARNED.md)*
|
||||||
455
BACKLOG.md
Normal file
455
BACKLOG.md
Normal file
@@ -0,0 +1,455 @@
|
|||||||
|
# Backlog - Future Features & Ideas
|
||||||
|
|
||||||
|
> **Purpose:** Long-term feature ideas, "what if" concepts, and parking lot items.
|
||||||
|
> **Note:** These are brainstorm items, not committed roadmap. Evaluate based on user demand and business impact.
|
||||||
|
> **Last Updated:** February 2, 2026
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Dynamic Script Generation](#dynamic-script-generation)
|
||||||
|
2. [Beyond Service Desk - Department Expansion](#beyond-service-desk---department-expansion)
|
||||||
|
3. [Tree Collaboration & Sharing](#tree-collaboration--sharing)
|
||||||
|
4. [Integration Ideas](#integration-ideas)
|
||||||
|
5. [Mobile & Accessibility](#mobile--accessibility)
|
||||||
|
6. [Gamification & Training](#gamification--training)
|
||||||
|
7. [Advanced Analytics](#advanced-analytics)
|
||||||
|
8. [AI-Powered Features](#ai-powered-features)
|
||||||
|
9. [Parking Lot - Quick Ideas](#parking-lot---quick-ideas)
|
||||||
|
10. [Long-Term Vision](#long-term-vision)
|
||||||
|
11. [Idea Evaluation Criteria](#idea-evaluation-criteria)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dynamic Script Generation
|
||||||
|
|
||||||
|
### Concept: Trees That Generate PowerShell Scripts
|
||||||
|
|
||||||
|
Instead of just guiding a tech through troubleshooting steps, trees could COLLECT information and OUTPUT executable scripts.
|
||||||
|
|
||||||
|
**Example Scenario: New User Onboarding**
|
||||||
|
|
||||||
|
A ticket comes in: "New hire starting Monday - John Smith, Marketing department"
|
||||||
|
|
||||||
|
Traditional approach:
|
||||||
|
1. Tech manually creates AD user
|
||||||
|
2. Tech looks up which groups Marketing needs
|
||||||
|
3. Tech adds user to groups one by one
|
||||||
|
4. Tech moves user to correct OU
|
||||||
|
5. Tech documents what they did
|
||||||
|
|
||||||
|
**Script Generation approach:**
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────┐
|
||||||
|
│ NEW USER ONBOARDING TREE │
|
||||||
|
├─────────────────────────────────────────────────────────────┤
|
||||||
|
│ Step 1: Enter user details │
|
||||||
|
│ First Name: [John_____________] │
|
||||||
|
│ Last Name: [Smith____________] │
|
||||||
|
│ Department: [Marketing________] ▼ │
|
||||||
|
│ │
|
||||||
|
│ Step 2: Select required groups (auto-suggested by dept) │
|
||||||
|
│ ☑ Domain Users │
|
||||||
|
│ ☑ Marketing-All │
|
||||||
|
│ ☑ SharePoint-Marketing │
|
||||||
|
│ │
|
||||||
|
│ Step 3: Confirm organizational unit │
|
||||||
|
│ OU Path: OU=Marketing,OU=Users,DC=contoso,DC=com │
|
||||||
|
│ │
|
||||||
|
│ [Generate Script] │
|
||||||
|
└─────────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Generated Output:**
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
# New User Creation Script
|
||||||
|
# Generated by Patherly - 2026-01-28 14:32
|
||||||
|
# Ticket: #12345
|
||||||
|
|
||||||
|
$Password = Read-Host -AsSecureString "Enter initial password"
|
||||||
|
New-ADUser -Name "John Smith" `
|
||||||
|
-GivenName "John" `
|
||||||
|
-Surname "Smith" `
|
||||||
|
-SamAccountName "jsmith" `
|
||||||
|
-UserPrincipalName "jsmith@contoso.com" `
|
||||||
|
-Path "OU=Marketing,OU=Users,DC=contoso,DC=com" `
|
||||||
|
-AccountPassword $Password `
|
||||||
|
-Enabled $true
|
||||||
|
|
||||||
|
# Add to groups
|
||||||
|
@("Domain Users", "Marketing-All", "SharePoint-Marketing") | ForEach-Object {
|
||||||
|
Add-ADGroupMember -Identity $_ -Members "jsmith"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Value Proposition:**
|
||||||
|
- Eliminates manual typing errors
|
||||||
|
- Ensures consistency across techs
|
||||||
|
- Auto-documents what was done
|
||||||
|
- Reduces training time for new hires
|
||||||
|
- Script can be reviewed before execution (safety)
|
||||||
|
|
||||||
|
### Other Script Generation Use Cases
|
||||||
|
|
||||||
|
| Use Case | Inputs Collected | Output |
|
||||||
|
|----------|------------------|--------|
|
||||||
|
| User Offboarding | Username, actions to take | Disable/remove script |
|
||||||
|
| Bulk Group Changes | User list, groups | Group membership script |
|
||||||
|
| Computer Setup | Name, department, user | Deployment script |
|
||||||
|
| Network Diagnostics | Issue description | Diagnostic collection script |
|
||||||
|
| M365 License Assignment | User, license type | PowerShell for M365 |
|
||||||
|
|
||||||
|
### Technical Considerations
|
||||||
|
|
||||||
|
**New Node Type: "Input Node"**
|
||||||
|
```typescript
|
||||||
|
interface InputNode {
|
||||||
|
type: 'input';
|
||||||
|
fields: InputField[];
|
||||||
|
validation?: ValidationRules;
|
||||||
|
next_node_id: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface InputField {
|
||||||
|
name: string;
|
||||||
|
label: string;
|
||||||
|
type: 'text' | 'select' | 'multiselect' | 'checkbox' | 'number';
|
||||||
|
options?: string[];
|
||||||
|
variable_name: string; // used in script template
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**New Node Type: "Script Output Node"**
|
||||||
|
```typescript
|
||||||
|
interface ScriptOutputNode {
|
||||||
|
type: 'script_output';
|
||||||
|
script_template: string; // PowerShell with {{variable}} placeholders
|
||||||
|
language: 'powershell' | 'bash' | 'python';
|
||||||
|
documentation_template?: string;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Safety & Compliance Features
|
||||||
|
|
||||||
|
- **Script Review Mode:** Scripts NEVER auto-execute, always presented for review
|
||||||
|
- **Audit Trail:** Log which scripts were generated and by whom
|
||||||
|
- **Template Approval:** Senior engineers review templates before publishing
|
||||||
|
- **Environment Variables:** Store org-specific values (domain name, OU paths)
|
||||||
|
|
||||||
|
### Implementation Phases
|
||||||
|
|
||||||
|
1. **Phase 1:** Basic script output with variable substitution
|
||||||
|
2. **Phase 2:** Input collection nodes with validation
|
||||||
|
3. **Phase 3:** Smart defaults (department → group suggestions)
|
||||||
|
4. **Phase 4:** Direct execution capability (Enterprise, with approval workflows)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Beyond Service Desk - Department Expansion
|
||||||
|
|
||||||
|
### Concept: Department-Specific Path Libraries
|
||||||
|
|
||||||
|
The "guided decision tree" concept applies to ANY process that benefits from consistency and documentation.
|
||||||
|
|
||||||
|
**Target Departments:**
|
||||||
|
|
||||||
|
| Department | Use Cases |
|
||||||
|
|------------|-----------|
|
||||||
|
| Service Desk | Troubleshooting (current focus) |
|
||||||
|
| Sales | Quoting, assessments, discovery |
|
||||||
|
| vCIO/Consulting | Policy creation, strategic planning |
|
||||||
|
| Onboarding | Client setup, documentation gathering |
|
||||||
|
| Finance | Contract review, billing disputes |
|
||||||
|
| HR | Employee onboarding, policy acknowledgment |
|
||||||
|
|
||||||
|
### vCIO / Consulting: Policy Builder
|
||||||
|
|
||||||
|
Guide clients through policy creation with smart templates and boilerplate language.
|
||||||
|
|
||||||
|
**Example: Acceptable Use Policy Builder**
|
||||||
|
|
||||||
|
User selects sections to include:
|
||||||
|
- ☑ Computer Use Policy
|
||||||
|
- ☑ Mobile Device Policy
|
||||||
|
- ☑ BYOD Policy
|
||||||
|
- ☑ AI Usage Policy
|
||||||
|
- ☑ Remote Work Policy
|
||||||
|
|
||||||
|
**Generated Output:** Complete, formatted policy document (Word/PDF) with:
|
||||||
|
- Professional boilerplate language
|
||||||
|
- Industry-specific compliance notes (HIPAA for healthcare, etc.)
|
||||||
|
- Signature/acknowledgment section
|
||||||
|
|
||||||
|
**Policy Types to Support:**
|
||||||
|
- Acceptable Use Policy (AUP)
|
||||||
|
- Information Security Policy
|
||||||
|
- Password Policy
|
||||||
|
- Data Classification Policy
|
||||||
|
- Incident Response Policy
|
||||||
|
- BYOD Policy
|
||||||
|
- AI/Generative AI Policy
|
||||||
|
|
||||||
|
**Value Proposition:**
|
||||||
|
- vCIOs generate client policies in minutes, not hours
|
||||||
|
- Consistent, professional output
|
||||||
|
- Industry-specific compliance built-in
|
||||||
|
- Upsell opportunity: "Policy Review" as a service
|
||||||
|
|
||||||
|
### Sales: Quote Builder & Assessment Paths
|
||||||
|
|
||||||
|
Guide sales reps through discovery with consistent methodology that surfaces upsell opportunities.
|
||||||
|
|
||||||
|
**Assessment Types:**
|
||||||
|
|
||||||
|
1. **Security Assessment** - Endpoint protection, MFA, training gaps
|
||||||
|
2. **Backup Assessment** - Frequency, retention, testing procedures
|
||||||
|
3. **Hardware Assessment** - Workstation age, server infrastructure, warranties
|
||||||
|
4. **Compliance Assessment** - HIPAA, PCI, documentation status
|
||||||
|
5. **Cloud Readiness Assessment** - Migration complexity, bandwidth needs
|
||||||
|
|
||||||
|
**Generated Outputs:**
|
||||||
|
- Gap Analysis Report (client-facing)
|
||||||
|
- Quote Worksheet (internal)
|
||||||
|
- Proposal Content (client-facing)
|
||||||
|
|
||||||
|
### Client Onboarding Paths
|
||||||
|
|
||||||
|
Structured onboarding ensuring nothing is missed:
|
||||||
|
- Contact gathering (technical, billing, decision makers)
|
||||||
|
- Credentials collection (secure vault integration)
|
||||||
|
- Documentation intake (passwords, network diagrams)
|
||||||
|
- Standards configuration (naming conventions, security policies)
|
||||||
|
- Tool deployment checklist
|
||||||
|
- Handoff to service desk
|
||||||
|
|
||||||
|
**Output:** Populated documentation templates, IT Glue/Hudu import-ready data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tree Collaboration & Sharing
|
||||||
|
|
||||||
|
### Public Tree Gallery
|
||||||
|
|
||||||
|
- Users publish trees to community gallery
|
||||||
|
- Rating and review system
|
||||||
|
- "Verified" badge for quality trees
|
||||||
|
- Fork and customize
|
||||||
|
|
||||||
|
### Tree Marketplace
|
||||||
|
|
||||||
|
- Premium trees from experts
|
||||||
|
- Revenue share model (70/30)
|
||||||
|
- Subscription access to premium library
|
||||||
|
|
||||||
|
### Tree Inheritance
|
||||||
|
|
||||||
|
- Company-wide "official" trees
|
||||||
|
- Teams create local variations
|
||||||
|
- Changes can be proposed upstream
|
||||||
|
- Version control and diff viewing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Integration Ideas
|
||||||
|
|
||||||
|
### PSA Deep Integration
|
||||||
|
|
||||||
|
- Create ticket from tree resolution
|
||||||
|
- Auto-populate ticket fields from session
|
||||||
|
- Link session to existing ticket
|
||||||
|
- Pull ticket context into tree suggestions
|
||||||
|
|
||||||
|
**Target PSAs:** ConnectWise, Kaseya, Autotask, ServiceNow
|
||||||
|
|
||||||
|
### RMM Integration
|
||||||
|
|
||||||
|
- Pull device info into tree context
|
||||||
|
- "This computer has X installed, skip to step Y"
|
||||||
|
- Trigger RMM scripts from tree actions
|
||||||
|
- Asset-aware troubleshooting
|
||||||
|
|
||||||
|
**Target RMMs:** Datto, ConnectWise Automate, NinjaRMM
|
||||||
|
|
||||||
|
### Documentation Integration
|
||||||
|
|
||||||
|
- Link tree nodes to IT Glue/Hudu articles
|
||||||
|
- Auto-create documentation from resolved sessions
|
||||||
|
- Sync tree content with knowledge base
|
||||||
|
|
||||||
|
### Communication Integration
|
||||||
|
|
||||||
|
- Slack/Teams notifications for escalations
|
||||||
|
- Share session summary to channel
|
||||||
|
- Request help from team within tree
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mobile & Accessibility
|
||||||
|
|
||||||
|
### Mobile App (PWA Enhancement)
|
||||||
|
|
||||||
|
- Offline tree access
|
||||||
|
- Voice input for hands-free use
|
||||||
|
- Camera integration for error screenshots
|
||||||
|
- Push notifications for shared sessions
|
||||||
|
|
||||||
|
### Voice-Guided Mode
|
||||||
|
|
||||||
|
- Read steps aloud
|
||||||
|
- Voice commands to navigate
|
||||||
|
- Useful for field techs with hands busy
|
||||||
|
- Accessibility for vision-impaired users
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Gamification & Training
|
||||||
|
|
||||||
|
### Tech Leaderboards
|
||||||
|
|
||||||
|
- Trees completed
|
||||||
|
- Resolution time improvements
|
||||||
|
- Contribution to tree improvements
|
||||||
|
- Points and badges
|
||||||
|
|
||||||
|
### Training Mode
|
||||||
|
|
||||||
|
- Practice trees without affecting stats
|
||||||
|
- Simulated scenarios
|
||||||
|
- Quiz mode with wrong-path feedback
|
||||||
|
- Certification preparation
|
||||||
|
|
||||||
|
### Onboarding Tracks
|
||||||
|
|
||||||
|
- Structured learning paths for new hires
|
||||||
|
- Progress tracking
|
||||||
|
- Manager visibility into training progress
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Advanced Analytics
|
||||||
|
|
||||||
|
### Predictive Issue Alerts
|
||||||
|
|
||||||
|
- "VPN issues spike on Mondays after updates"
|
||||||
|
- Proactive notifications to prepare
|
||||||
|
- Trend forecasting
|
||||||
|
|
||||||
|
### Cost Attribution
|
||||||
|
|
||||||
|
- Estimate time spent per issue type
|
||||||
|
- Calculate cost of common problems
|
||||||
|
- ROI justification for fixes
|
||||||
|
|
||||||
|
### Comparative Analytics
|
||||||
|
|
||||||
|
- Benchmark against anonymized industry data
|
||||||
|
- "Your password reset time is 20% faster than average"
|
||||||
|
- Identify improvement opportunities
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## AI-Powered Features
|
||||||
|
|
||||||
|
### Conversational Interface
|
||||||
|
|
||||||
|
- Chat with AI about an issue
|
||||||
|
- AI suggests relevant trees
|
||||||
|
- Natural language navigation
|
||||||
|
|
||||||
|
### Auto-Tree Generation
|
||||||
|
|
||||||
|
- Record a senior tech explaining a fix
|
||||||
|
- AI generates tree structure from transcript
|
||||||
|
- Review and publish
|
||||||
|
|
||||||
|
### Predictive Resolution
|
||||||
|
|
||||||
|
- AI predicts likely resolution before tree starts
|
||||||
|
- "Based on the description, this is probably X (85% confidence)"
|
||||||
|
- Option to jump to likely solution
|
||||||
|
|
||||||
|
### Import from Text/Documentation
|
||||||
|
|
||||||
|
- Paste existing runbook or documentation
|
||||||
|
- AI parses and creates tree structure
|
||||||
|
- Review and refine
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Parking Lot - Quick Ideas
|
||||||
|
|
||||||
|
*Quick-capture ideas to evaluate later:*
|
||||||
|
|
||||||
|
- [ ] Browser extension to capture screenshots into sessions
|
||||||
|
- [ ] QR codes on physical equipment linking to relevant trees
|
||||||
|
- [ ] Customer-facing trees (end-user self-service)
|
||||||
|
- [ ] Tree templates for common scenarios
|
||||||
|
- [ ] Scheduled tree reminders (monthly server maintenance checklist)
|
||||||
|
- [ ] Integration with monitoring tools (trigger tree from alert)
|
||||||
|
- [ ] Multi-language tree support
|
||||||
|
- [ ] Conditional logic based on time of day / day of week
|
||||||
|
- [ ] SLA timers visible during session
|
||||||
|
- [ ] Escalation workflows with approval chains
|
||||||
|
- [ ] Custom note formatting templates for different ticket systems
|
||||||
|
- [ ] "Options on the go" - select pre-made steps mid-tree and jump to relevant point
|
||||||
|
- [ ] Import plan function - write in text format and import as tree
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Long-Term Vision (Year 2+)
|
||||||
|
|
||||||
|
### Product Evolution
|
||||||
|
|
||||||
|
- Self-learning system (trees improve automatically based on usage)
|
||||||
|
- Voice-guided troubleshooting (hands-free operation)
|
||||||
|
- AR/VR support (on-site equipment identification)
|
||||||
|
- AI co-pilot (real-time suggestions during troubleshooting)
|
||||||
|
|
||||||
|
### Market Expansion
|
||||||
|
|
||||||
|
- Vertical-specific tree libraries (healthcare IT, financial services, education)
|
||||||
|
- Certification program for tree authors
|
||||||
|
- Professional services (custom tree development)
|
||||||
|
- Training and consultation services
|
||||||
|
|
||||||
|
### Platform Maturity
|
||||||
|
|
||||||
|
- 99.9% uptime SLA
|
||||||
|
- Global CDN deployment
|
||||||
|
- Advanced compliance (SOC 2, ISO 27001)
|
||||||
|
- Enterprise support tiers
|
||||||
|
- White-glove onboarding
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Idea Evaluation Criteria
|
||||||
|
|
||||||
|
When evaluating which ideas to pursue:
|
||||||
|
|
||||||
|
| Criteria | Weight | Questions |
|
||||||
|
|----------|--------|-----------|
|
||||||
|
| User demand | High | Are users asking for this? |
|
||||||
|
| Revenue impact | High | Will this drive upgrades or reduce churn? |
|
||||||
|
| Differentiation | Medium | Does this set us apart from alternatives? |
|
||||||
|
| Development effort | Medium | How long to build MVP? |
|
||||||
|
| Maintenance burden | Medium | Ongoing cost to support? |
|
||||||
|
| Strategic fit | Medium | Does this align with our vision? |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How to Add Ideas
|
||||||
|
|
||||||
|
When adding new ideas to this document:
|
||||||
|
|
||||||
|
1. **Describe the concept** - What is it? Why would users want it?
|
||||||
|
2. **Provide an example** - Concrete scenario showing the feature in action
|
||||||
|
3. **Note technical considerations** - What would need to change?
|
||||||
|
4. **Estimate complexity** - Simple / Medium / Complex
|
||||||
|
5. **Identify dependencies** - What needs to exist first?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This is a living document. Add ideas freely, evaluate periodically, and move promising concepts to GitHub Issues when ready to implement.*
|
||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
> **Purpose:** Quick-reference file showing exactly where the project stands.
|
> **Purpose:** Quick-reference file showing exactly where the project stands.
|
||||||
> **For Claude Code:** Read this first to understand what's done and what's next.
|
> **For Claude Code:** Read this first to understand what's done and what's next.
|
||||||
> **Last Updated:** January 29, 2026
|
> **Last Updated:** February 2, 2026
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
414
docs/GITHUB-ISSUES-MIGRATION.md
Normal file
414
docs/GITHUB-ISSUES-MIGRATION.md
Normal file
@@ -0,0 +1,414 @@
|
|||||||
|
# GitHub Issues Migration Instructions
|
||||||
|
|
||||||
|
> **For Claude Code:** Use these instructions to set up GitHub Issues for Patherly
|
||||||
|
> **Repository:** github.com/patherly/patherly
|
||||||
|
> **Date:** February 2, 2026
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Create Labels
|
||||||
|
|
||||||
|
Create the following labels in the repository:
|
||||||
|
|
||||||
|
| Label | Color (hex) | Description |
|
||||||
|
|-------|-------------|-------------|
|
||||||
|
| `bug` | `d73a4a` | Something isn't working |
|
||||||
|
| `feature` | `0e8a16` | New functionality |
|
||||||
|
| `enhancement` | `a2eeef` | Improvement to existing feature |
|
||||||
|
| `documentation` | `0075ca` | Documentation updates |
|
||||||
|
| `backend` | `7057ff` | FastAPI/Python work |
|
||||||
|
| `frontend` | `fbca04` | React work |
|
||||||
|
| `database` | `b60205` | PostgreSQL/schema changes |
|
||||||
|
| `priority: high` | `d93f0b` | Do this soon |
|
||||||
|
| `priority: medium` | `fbca04` | Important but not urgent |
|
||||||
|
| `priority: low` | `c5def5` | Nice to have |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Create Milestones
|
||||||
|
|
||||||
|
| Milestone | Description | Due Date |
|
||||||
|
|-----------|-------------|----------|
|
||||||
|
| Phase 2 Completion | Tree editor polish, deployment | (leave open) |
|
||||||
|
| Phase 2.5 | Personal branching, step library | (leave open) |
|
||||||
|
| Backlog | Ideas not yet scheduled | (no due date) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Create Issues
|
||||||
|
|
||||||
|
### Phase 2 Remaining (3 issues)
|
||||||
|
|
||||||
|
**Issue 1:**
|
||||||
|
- Title: Tree Editor Validation - required fields and orphan detection
|
||||||
|
- Labels: `feature`, `frontend`, `priority: high`
|
||||||
|
- Milestone: Phase 2 Completion
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Add validation to the tree editor:
|
||||||
|
- [ ] Required fields validation (name, at least one node)
|
||||||
|
- [ ] Orphan node detection (nodes not reachable from root)
|
||||||
|
- [ ] Circular reference detection
|
||||||
|
- [ ] Show validation errors before save
|
||||||
|
- [ ] Prevent save if validation fails
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 2:**
|
||||||
|
- Title: User Preferences - export format default setting
|
||||||
|
- Labels: `feature`, `frontend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2 Completion
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Add export format preference to user settings:
|
||||||
|
- [ ] Add "Default Export Format" dropdown in settings (Markdown/Text/HTML)
|
||||||
|
- [ ] Persist preference in localStorage
|
||||||
|
- [ ] Use preference as default in export dialog
|
||||||
|
- [ ] Dark mode toggle already complete ✅
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 3:**
|
||||||
|
- Title: Deploy to Railway - CI/CD pipeline setup
|
||||||
|
- Labels: `feature`, `priority: high`
|
||||||
|
- Milestone: Phase 2 Completion
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Set up production deployment on Railway Pro:
|
||||||
|
- [ ] Configure Railway project with 3 services (PostgreSQL, backend, frontend)
|
||||||
|
- [ ] Set up environment variables
|
||||||
|
- [ ] Configure custom domains (patherly.com, api.patherly.com)
|
||||||
|
- [ ] Set up PR environments for testing
|
||||||
|
- [ ] Document deployment process
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2.5 Features (15 issues)
|
||||||
|
|
||||||
|
**Issue 4:**
|
||||||
|
- Title: Step Categories - database table and seed data
|
||||||
|
- Labels: `feature`, `backend`, `database`, `priority: high`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create step_categories table for organizing the step library:
|
||||||
|
- [ ] Create Alembic migration for step_categories table
|
||||||
|
- [ ] Add SQLAlchemy model
|
||||||
|
- [ ] Seed default categories (Citrix/VDI, Active Directory, Microsoft 365, Networking, etc.)
|
||||||
|
- [ ] Create API endpoints for category CRUD (admin only)
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 5:**
|
||||||
|
- Title: Step Library - database schema and migrations
|
||||||
|
- Labels: `feature`, `backend`, `database`, `priority: high`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create step_library table for reusable troubleshooting steps:
|
||||||
|
- [ ] Create Alembic migration
|
||||||
|
- [ ] Add SQLAlchemy model with fields: title, step_type, content (JSONB), visibility, category_id, tags, ratings aggregates
|
||||||
|
- [ ] Add indexes for search and filtering
|
||||||
|
- [ ] Add step_ratings table for user ratings/reviews
|
||||||
|
- [ ] Add step_usage_log table for "Verified Use" tracking
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 6:**
|
||||||
|
- Title: Step Library - CRUD API endpoints
|
||||||
|
- Labels: `feature`, `backend`, `priority: high`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create API endpoints for step library:
|
||||||
|
- [ ] GET /api/v1/steps - List steps with filters (visibility, category, tags, rating)
|
||||||
|
- [ ] GET /api/v1/steps/{id} - Get step details
|
||||||
|
- [ ] POST /api/v1/steps - Create new step
|
||||||
|
- [ ] PUT /api/v1/steps/{id} - Update step
|
||||||
|
- [ ] DELETE /api/v1/steps/{id} - Soft delete
|
||||||
|
- [ ] GET /api/v1/steps/search - Full-text search
|
||||||
|
- [ ] GET /api/v1/steps/tags/popular - Popular tags
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 7:**
|
||||||
|
- Title: Step Library - rating and review system
|
||||||
|
- Labels: `feature`, `backend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Implement step rating and review system:
|
||||||
|
- [ ] POST /api/v1/steps/{id}/rate - Rate a step (1-5 stars + optional review)
|
||||||
|
- [ ] PUT /api/v1/steps/{id}/rate - Update rating
|
||||||
|
- [ ] DELETE /api/v1/steps/{id}/rate - Remove rating
|
||||||
|
- [ ] POST /api/v1/steps/{id}/helpful - Vote helpful (yes/no)
|
||||||
|
- [ ] GET /api/v1/steps/{id}/reviews - Get reviews
|
||||||
|
- [ ] Track "Verified Use" when step is actually used in a session
|
||||||
|
- [ ] Calculate and update aggregated ratings on step_library table
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 8:**
|
||||||
|
- Title: Add Custom Step button in tree navigation
|
||||||
|
- Labels: `feature`, `frontend`, `priority: high`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Add ability to insert custom steps during active troubleshooting:
|
||||||
|
- [ ] Add "+ Add Custom Step" button at each decision node
|
||||||
|
- [ ] Button opens modal with two tabs: "Type My Own" and "Browse Library"
|
||||||
|
- [ ] Custom steps inserted into session only (not original tree)
|
||||||
|
- [ ] Visual indicator showing step is custom/user-added
|
||||||
|
- [ ] Custom steps included in session export
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 9:**
|
||||||
|
- Title: Custom step creation modal
|
||||||
|
- Labels: `feature`, `frontend`, `priority: high`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create modal for adding custom steps:
|
||||||
|
- [ ] Tab 1: "Type My Own" - form to create step (type, title, description, commands)
|
||||||
|
- [ ] Tab 2: "Browse Library" - search and select from step library
|
||||||
|
- [ ] Option to save custom step to personal library
|
||||||
|
- [ ] Validate step before insertion
|
||||||
|
- [ ] Insert step into current session
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 10:**
|
||||||
|
- Title: Step library browser component
|
||||||
|
- Labels: `feature`, `frontend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create UI component for browsing step library:
|
||||||
|
- [ ] Search input with full-text search
|
||||||
|
- [ ] Category filter dropdown
|
||||||
|
- [ ] Tag filter (show popular tags as chips)
|
||||||
|
- [ ] Minimum rating filter
|
||||||
|
- [ ] Sort options (recent, popular, rating)
|
||||||
|
- [ ] Step cards showing title, type, rating, usage count
|
||||||
|
- [ ] Step preview/detail modal
|
||||||
|
- [ ] Insert button to add to session
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 11:**
|
||||||
|
- Title: User Trees - database schema
|
||||||
|
- Labels: `feature`, `backend`, `database`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create user_trees table for personal/forked trees:
|
||||||
|
- [ ] Create Alembic migration
|
||||||
|
- [ ] Fields: user_id, forked_from_tree_id, name, tree_content (JSONB), visibility, share_token
|
||||||
|
- [ ] Add session_custom_steps table to track custom steps per session
|
||||||
|
- [ ] Add indexes for user lookup and share token
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 12:**
|
||||||
|
- Title: Tree forking API endpoint
|
||||||
|
- Labels: `feature`, `backend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create API for forking trees:
|
||||||
|
- [ ] POST /api/v1/user-trees/fork/{tree_id} - Fork an official tree
|
||||||
|
- [ ] Deep copy tree structure to user_trees
|
||||||
|
- [ ] Track lineage (forked_from_tree_id, forked_at_version)
|
||||||
|
- [ ] Increment fork_count on original tree
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 13:**
|
||||||
|
- Title: User Trees - CRUD endpoints
|
||||||
|
- Labels: `feature`, `backend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create API endpoints for user tree management:
|
||||||
|
- [ ] GET /api/v1/user-trees - List user's custom trees
|
||||||
|
- [ ] GET /api/v1/user-trees/{id} - Get custom tree
|
||||||
|
- [ ] POST /api/v1/user-trees - Create new custom tree
|
||||||
|
- [ ] PUT /api/v1/user-trees/{id} - Update custom tree
|
||||||
|
- [ ] DELETE /api/v1/user-trees/{id} - Soft delete
|
||||||
|
- [ ] PUT /api/v1/user-trees/{id}/share - Update sharing settings
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 14:**
|
||||||
|
- Title: My Trees dashboard page
|
||||||
|
- Labels: `feature`, `frontend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Create "My Trees" page for managing personal trees:
|
||||||
|
- [ ] List user's forked/custom trees
|
||||||
|
- [ ] Show original tree reference (if forked)
|
||||||
|
- [ ] Last used date, usage count
|
||||||
|
- [ ] Quick actions: start session, edit, share, delete
|
||||||
|
- [ ] Fork button on tree detail view
|
||||||
|
- [ ] Notification when original tree updated (basic)
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 15:**
|
||||||
|
- Title: Tree sharing via link
|
||||||
|
- Labels: `feature`, `frontend`, `backend`, `priority: medium`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Allow sharing trees via link:
|
||||||
|
- [ ] Generate unique share token for tree
|
||||||
|
- [ ] GET /api/v1/shared/{share_token} - Access shared tree (no auth required)
|
||||||
|
- [ ] Share modal with visibility options (private, link, team, public)
|
||||||
|
- [ ] Copy link button
|
||||||
|
- [ ] Option to allow/disallow forking
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 16:**
|
||||||
|
- Title: Save session as custom tree
|
||||||
|
- Labels: `feature`, `frontend`, `backend`, `priority: low`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
After completing a session with custom steps, offer to save as tree:
|
||||||
|
- [ ] POST /api/v1/sessions/{id}/save-as-tree endpoint
|
||||||
|
- [ ] Prompt user after session completion (if custom steps were added)
|
||||||
|
- [ ] Create user_tree from session path + custom steps
|
||||||
|
- [ ] Allow user to name and edit before saving
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 17:**
|
||||||
|
- Title: Admin - category management UI
|
||||||
|
- Labels: `feature`, `frontend`, `priority: low`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Admin interface for managing step categories:
|
||||||
|
- [ ] List categories with step counts
|
||||||
|
- [ ] Create new category
|
||||||
|
- [ ] Edit category name/description
|
||||||
|
- [ ] Archive category (soft delete)
|
||||||
|
- [ ] Reorder categories (display_order)
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 18:**
|
||||||
|
- Title: Rate/review modal after using a step
|
||||||
|
- Labels: `feature`, `frontend`, `priority: low`
|
||||||
|
- Milestone: Phase 2.5
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
Prompt users to rate steps after using them:
|
||||||
|
- [ ] After session completion, show steps used from library
|
||||||
|
- [ ] Rating modal with 1-5 stars
|
||||||
|
- [ ] Optional written review (max 500 chars)
|
||||||
|
- [ ] "Was this helpful?" quick vote
|
||||||
|
- [ ] Mark rating as "Verified Use"
|
||||||
|
|
||||||
|
Reference: PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Known Bugs (create as closed issues for history)
|
||||||
|
|
||||||
|
**Issue 19:**
|
||||||
|
- Title: [FIXED] DateTime timezone handling causing Internal Server Errors
|
||||||
|
- Labels: `bug`, `backend`
|
||||||
|
- State: CLOSED
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
**Problem:** Mixing timezone-aware and timezone-naive datetime objects caused errors in session completion.
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
- Updated all SQLAlchemy models to use `DateTime(timezone=True)`
|
||||||
|
- Changed all default datetime factories to `lambda: datetime.now(timezone.utc)`
|
||||||
|
|
||||||
|
**Files affected:** All models with timestamp fields
|
||||||
|
|
||||||
|
Fixed: January 28, 2026
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 20:**
|
||||||
|
- Title: [FIXED] bcrypt/passlib version compatibility
|
||||||
|
- Labels: `bug`, `backend`
|
||||||
|
- State: CLOSED
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
**Problem:** Password hashing failed with newer bcrypt versions.
|
||||||
|
|
||||||
|
**Solution:** Pin bcrypt version in requirements.txt:
|
||||||
|
- bcrypt==4.0.1
|
||||||
|
- passlib[bcrypt]==1.7.4
|
||||||
|
|
||||||
|
Fixed: January 2026
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 21:**
|
||||||
|
- Title: [FIXED] Email validation rejecting .local domains
|
||||||
|
- Labels: `bug`, `backend`
|
||||||
|
- State: CLOSED
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
**Problem:** Seed script failed with email validation error when using `.local` TLD.
|
||||||
|
|
||||||
|
**Cause:** email-validator library correctly rejects `.local` as reserved per RFC 6761.
|
||||||
|
|
||||||
|
**Solution:** Use standard domains like `example.com` for seed/test users.
|
||||||
|
|
||||||
|
Fixed: January 29, 2026
|
||||||
|
```
|
||||||
|
|
||||||
|
**Issue 22:**
|
||||||
|
- Title: [FIXED] httpx not installed for seed scripts
|
||||||
|
- Labels: `bug`, `backend`
|
||||||
|
- State: CLOSED
|
||||||
|
- Body:
|
||||||
|
```
|
||||||
|
**Problem:** Running seed_trees.py failed with ModuleNotFoundError for httpx.
|
||||||
|
|
||||||
|
**Solution:** Install httpx before running seed scripts:
|
||||||
|
```
|
||||||
|
pip install httpx
|
||||||
|
```
|
||||||
|
|
||||||
|
Fixed: January 29, 2026
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Verify
|
||||||
|
|
||||||
|
After creating all issues:
|
||||||
|
1. Check that labels appear correctly
|
||||||
|
2. Check that milestones have correct issues assigned
|
||||||
|
3. Verify closed issues show in closed state
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Issues 4-18 are Phase 2.5 features from PHASE-2.5-PERSONAL-BRANCHING.md
|
||||||
|
- Issues 19-22 are historical bugs documented in LESSONS-LEARNED.md (create as closed)
|
||||||
|
- Long-term feature ideas are in BACKLOG.md (not GitHub Issues yet)
|
||||||
Reference in New Issue
Block a user