diff --git a/CLAUDE.md b/CLAUDE.md index 2abba3d4..d4343d40 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,7 @@ - **Layout:** App shell with persistent sidebar + top bar + main content (CSS Grid). Two fixed atmosphere orbs (cyan top-right, purple bottom-left) behind the shell for ambient glow. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) - **Navigation:** Sidebar nav with type sub-items (All Flows → Troubleshooting / Projects / Maintenance). Pinned flows section for quick access. NO workspace switcher. See [UI-DESIGN-SYSTEM.md](UI-DESIGN-SYSTEM.md) - **Terminology:** User-facing label is "Flows" (not "Trees"). Procedural flows are called "Projects" in the UI. Maintenance flows are called "Maintenance" in the UI. `tree_type` column values unchanged in DB. -- **Rebrand guide:** [REBRAND-IMPLEMENTATION-GUIDE.md](REBRAND-IMPLEMENTATION-GUIDE.md) +- **Rebrand guide:** [REBRAND-IMPLEMENTATION-GUIDE.md](docs/archive/REBRAND-IMPLEMENTATION-GUIDE.md) **Component styling rules:** diff --git a/DEV-ENV.md b/DEV-ENV.md new file mode 100644 index 00000000..7a65f77c --- /dev/null +++ b/DEV-ENV.md @@ -0,0 +1,350 @@ +# DevServer01 Environment Setup & Operations Guide + +## Server Overview + +- **Hostname:** devserver01 +- **IP Address:** 192.168.0.9 +- **OS:** Ubuntu 25.10 (Questing Quokka) +- **CPU:** AMD Ryzen 3 PRO 3200GE w/ Radeon Vega Graphics +- **RAM:** ~5.2GB (some reserved by Vega iGPU) +- **Disk:** 57GB LVM volume (`/dev/mapper/ubuntu--vg-ubuntu--lv`), ~47GB free +- **Hardware:** Lenovo ThinkCentre Micro Tower + +## Docker Setup + +Docker was installed via the official convenience script: + +```bash +curl -fsSL https://get.docker.com | sh +sudo usermod -aG docker michael +``` + +Docker Compose is included with this installation. + +## Code-Server + +### Overview + +Code-server (codercom/code-server) runs in a Docker container, providing a browser-accessible VS Code instance at `https://192.168.0.9:8080`. It uses a custom Dockerfile to include additional tools like `gh` (GitHub CLI). + +### Custom Dockerfile + +Location: `~/docker/Dockerfile.code-server` + +```dockerfile +FROM codercom/code-server:latest + +USER root +RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && \ + chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg && \ + echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \ + apt update && apt install -y gh && \ + rm -rf /var/lib/apt/lists/* +USER coder +``` + +### Docker Compose File + +Location: `~/docker/docker-compose.yml` + +```yaml +services: + code-server: + build: + context: . + dockerfile: Dockerfile.code-server + container_name: code-server + environment: + - PASSWORD= + volumes: + - ./code-server/config/data:/home/coder/.local/share/code-server + - ./code-server/config/extensions:/home/coder/.local/share/code-server/extensions + - ./code-server/config/.config/code-server:/home/coder/.config/code-server + - ./projects:/projects + - ./code-server/certs:/certs + - /home/michael/.claude:/home/coder/.claude + ports: + - 8080:8443 + command: --bind-addr 0.0.0.0:8443 --cert /certs/cert.pem --cert-key /certs/key.pem /projects + user: "1000:1000" + restart: unless-stopped +``` + +### Key Details + +- **Container user:** `coder` (UID 1000) +- **Home directory inside container:** `/home/coder` +- **Projects mount:** Host `~/docker/projects` → Container `/projects` +- **Claude Code config mount:** Host `/home/michael/.claude` → Container `/home/coder/.claude` +- **HTTPS:** Self-signed certs via a custom Homelab CA +- **Internal port:** 8443 (code-server listens here) +- **External port:** 8080 (mapped to 8443 internally) +- **Access URL:** `https://192.168.0.9:8080` + +### SSL Certificates + +Location: `~/docker/code-server/certs/` + +A custom Certificate Authority (CA) was created for the homelab: + +- `ca.key` — CA private key +- `ca.crt` — CA certificate (imported into browsers to trust all homelab certs) +- `key.pem` — code-server private key +- `cert.pem` — code-server certificate (signed by CA) +- `server.cnf` — OpenSSL config with SANs for devserver01 + +The CA cert (`ca.crt`) has been imported into Firefox on client machines under Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import → "Trust this CA to identify websites." + +### Volume Mapping Reference + +| Host Path | Container Path | Purpose | +|---|---|---| +| `~/docker/code-server/config/data` | `/home/coder/.local/share/code-server` | VS Code user data, settings | +| `~/docker/code-server/config/extensions` | `/home/coder/.local/share/code-server/extensions` | VS Code extensions | +| `~/docker/code-server/config/.config/code-server` | `/home/coder/.config/code-server` | code-server config | +| `~/docker/projects` | `/projects` | All project repos | +| `~/docker/code-server/certs` | `/certs` | SSL certificates | +| `/home/michael/.claude` | `/home/coder/.claude` | Claude Code config, plugins, skills, history | + +## Patherly / ResolutionFlow Dev Environment + +### Docker Compose (Dev) + +Location: `~/docker/projects/patherly/docker-compose.dev.yml` + +This runs the full Patherly/ResolutionFlow stack: + +- **PostgreSQL** (pgvector/pgvector:pg16) on port 5432 +- **Backend** (FastAPI/Uvicorn) on port 8000 +- **Frontend** (Vite/React) on port 5173 + +### Environment Files + +- `~/docker/projects/patherly/.env` — Backend secrets (SECRET_KEY, API keys, etc.) +- `~/docker/projects/patherly/frontend/.env` — Frontend config (VITE_API_URL) + +### Critical Configuration for Remote Access + +Since the dev environment is accessed from other machines on the LAN (not localhost), these settings are required: + +**Frontend `.env`:** +``` +VITE_API_URL=http://192.168.0.9:8000 +``` + +**Backend CORS_ORIGINS in `docker-compose.dev.yml`:** +```yaml +- CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","http://127.0.0.1:3000","http://127.0.0.1:5173","http://192.168.0.9:5173","http://192.168.0.9:3000"] +``` + +The `192.168.0.9` entries are required because browsers make requests from the client machine, where `localhost` refers to the client — not devserver01. + +### Starting the Dev Environment + +```bash +cd ~/docker/projects/patherly +docker compose -f docker-compose.dev.yml up -d +``` + +### Running Migrations (Fresh Database) + +```bash +docker compose -f docker-compose.dev.yml run --rm backend alembic upgrade head +``` + +### Seeding Test Users + +```bash +docker exec resolutionflow_backend python -m scripts.seed_test_users +``` + +### Rebuilding After Frontend .env Changes + +Vite bakes environment variables at build time, so changes to `VITE_API_URL` require a rebuild: + +```bash +docker compose -f docker-compose.dev.yml down +docker compose -f docker-compose.dev.yml up -d --build +``` + +Backend environment changes (like CORS_ORIGINS) only need a restart, not a rebuild. + +### Access URLs + +- **Frontend:** `http://192.168.0.9:5173` +- **Backend API:** `http://192.168.0.9:8000` +- **API Docs:** `http://192.168.0.9:8000/docs` + +## Known Issues & Fixes + +### iptables DROP Rules Blocking Docker Traffic + +Docker routes container traffic through the FORWARD chain. Rogue DROP rules in the DOCKER chain can block all container networking. + +**Symptoms:** Container shows as running, port is listening via `ss`, but `curl` returns "Connection reset by peer" or "Connection refused" from other machines. + +**Diagnosis:** +```bash +sudo iptables -L DOCKER -n --line-numbers +``` + +Look for blanket DROP rules: +``` +2 DROP all -- 0.0.0.0/0 0.0.0.0/0 +3 DROP all -- 0.0.0.0/0 0.0.0.0/0 +``` + +**Fix:** +```bash +# Remove DROP rules (remove highest numbered first) +sudo iptables -D DOCKER 3 +sudo iptables -D DOCKER 2 +``` + +If the FORWARD chain has `policy DROP` and Docker containers can't communicate: +```bash +sudo systemctl restart docker +``` + +Docker rebuilds its iptables chains on restart. These rules don't persist across reboots by default — if they come back, something else is creating them. + +### Code-Server Port Mismatch + +The codercom/code-server image listens on port **8443** internally, not 8080. The compose file must map `8080:8443`: + +```yaml +ports: + - 8080:8443 +``` + +The code-server config file (`/home/coder/.config/code-server/config.yaml`) must bind to `0.0.0.0`, not `127.0.0.1`: + +```yaml +bind-addr: 0.0.0.0:8443 +``` + +If it says `127.0.0.1`, it will only accept connections from inside the container. + +### Permission Issues Inside Container + +The container runs as user `coder` (UID 1000). Host files mounted into the container must be owned by UID 1000: + +```bash +# Fix project permissions +sudo chown -R 1000:1000 ~/docker/projects + +# Fix code-server config permissions +sudo chown -R 1000:1000 ~/docker/code-server/config/ + +# Fix Claude Code config permissions +sudo chown -R 1000:1000 ~/.claude/ +``` + +### GitHub CLI (gh) Auth + +gh stores its config at `/home/coder/.config/gh/`. If it fails with permission denied: + +```bash +docker exec -u root code-server mkdir -p /home/coder/.config/gh +docker exec -u root code-server chown -R 1000:1000 /home/coder/.config +``` + +## Useful Commands + +### Check all running containers +```bash +docker ps +``` + +### View logs for a specific container +```bash +docker logs --tail 30 +``` + +### Restart code-server +```bash +cd ~/docker +docker compose up -d +``` + +### Rebuild code-server (after Dockerfile changes) +```bash +cd ~/docker +docker compose down +docker compose up -d --build +``` + +### Restart dev environment +```bash +cd ~/docker/projects/patherly +docker compose -f docker-compose.dev.yml down +docker compose -f docker-compose.dev.yml up -d +``` + +### SSH into devserver01 +```bash +ssh michael@192.168.0.9 +``` + +### Check what's listening on ports +```bash +sudo ss -tlnp | grep +``` + +### Check firewall / iptables +```bash +sudo ufw status +sudo iptables -L -n --line-numbers +sudo iptables -L DOCKER -n --line-numbers +``` + +### Execute commands inside containers +```bash +# As default user +docker exec code-server + +# As root +docker exec -u root code-server + +# Interactive shell +docker exec -it code-server bash +``` + +## Network Info + +- **Server IP:** 192.168.0.9 +- **Docker bridge network:** 172.17.0.0/16 and 172.18.0.0/16 +- **Host user:** michael (UID 1000) +- **Container user:** coder (UID 1000) — same UID allows seamless file sharing via volume mounts + +## Code-Server Browser Tips + +- **Command Palette:** `F1` (not Ctrl+Shift+P, which opens Firefox private window) +- **Context Menu (right-click):** `Alt + Right Click` +- **Terminal:** `` Ctrl+` `` +- **Rename file:** `F2` +- **Go to definition:** `F12` +- **Find references:** `Shift+F12` + +## Adding New Tools to Code-Server + +To permanently add tools (survive container restarts), add them to `~/docker/Dockerfile.code-server`: + +```dockerfile +USER root +RUN apt update && apt install -y && rm -rf /var/lib/apt/lists/* +USER coder +``` + +Then rebuild: +```bash +cd ~/docker +docker compose down +docker compose up -d --build +``` + +For temporary installs (gone after restart): +```bash +docker exec -u root code-server apt update +docker exec -u root code-server apt install -y +``` \ No newline at end of file diff --git a/QUICK-START.md b/docs/QUICK-START.md similarity index 100% rename from QUICK-START.md rename to docs/QUICK-START.md diff --git a/docs/ResolutionFlow_Pivot_Architecture.docx b/docs/ResolutionFlow_Pivot_Architecture.docx new file mode 100644 index 00000000..bbd3e4eb Binary files /dev/null and b/docs/ResolutionFlow_Pivot_Architecture.docx differ diff --git a/ARCHITECTURE.md b/docs/archive/ARCHITECTURE.md similarity index 100% rename from ARCHITECTURE.md rename to docs/archive/ARCHITECTURE.md diff --git a/BACKLOG.md b/docs/archive/BACKLOG.md similarity index 100% rename from BACKLOG.md rename to docs/archive/BACKLOG.md diff --git a/CLAUDE-SETUP.md b/docs/archive/CLAUDE-SETUP.md similarity index 100% rename from CLAUDE-SETUP.md rename to docs/archive/CLAUDE-SETUP.md diff --git a/IMPLEMENTATION-SUMMARY-ISSUE-34.md b/docs/archive/IMPLEMENTATION-SUMMARY-ISSUE-34.md similarity index 100% rename from IMPLEMENTATION-SUMMARY-ISSUE-34.md rename to docs/archive/IMPLEMENTATION-SUMMARY-ISSUE-34.md diff --git a/MICHAEL-NOTES.md b/docs/archive/MICHAEL-NOTES.md similarity index 100% rename from MICHAEL-NOTES.md rename to docs/archive/MICHAEL-NOTES.md diff --git a/PHASE-2.5-PERSONAL-BRANCHING.md b/docs/archive/PHASE-2.5-PERSONAL-BRANCHING.md similarity index 100% rename from PHASE-2.5-PERSONAL-BRANCHING.md rename to docs/archive/PHASE-2.5-PERSONAL-BRANCHING.md diff --git a/REBRAND-IMPLEMENTATION-GUIDE.md b/docs/archive/REBRAND-IMPLEMENTATION-GUIDE.md similarity index 100% rename from REBRAND-IMPLEMENTATION-GUIDE.md rename to docs/archive/REBRAND-IMPLEMENTATION-GUIDE.md diff --git a/TS-EXAMPLES.md b/docs/archive/TS-EXAMPLES.md similarity index 100% rename from TS-EXAMPLES.md rename to docs/archive/TS-EXAMPLES.md diff --git a/WORKSPACE-REMOVAL-PLAN.md b/docs/archive/WORKSPACE-REMOVAL-PLAN.md similarity index 100% rename from WORKSPACE-REMOVAL-PLAN.md rename to docs/archive/WORKSPACE-REMOVAL-PLAN.md diff --git a/docs/marketing/resolutionflow-one-pager-print.html b/docs/marketing/resolutionflow-one-pager-print.html new file mode 100644 index 00000000..c46bbd31 --- /dev/null +++ b/docs/marketing/resolutionflow-one-pager-print.html @@ -0,0 +1,393 @@ + + + + +ResolutionFlow — Flyer + + + +
+ + +
+
+ + + + + + + + + + + + + + + +
ResolutionFlow
+
+

Stop Reinventing Fixes.
Build a Knowledge Engine.

+

Guided troubleshooting flows, AI-assisted resolution, and auto-generated ticket documentation for MSP teams.

+
Built for Managed Service Providers
+
+ + +
+ + +
+

Your best engineers' knowledge shouldn't live only in their heads.

+

Every time a senior tech leaves, tribal knowledge goes with them. Junior engineers waste hours reinventing solutions that already exist. Ticket notes are inconsistent. Resolution times are unpredictable.

+
+ + +
+
+
//
+
+

Guided Troubleshooting Flows

+

Turn your best engineers' proven processes into reusable decision trees that anyone on the team can follow.

+
+
+
+
AI
+
+

AI Copilot (FlowPilot)

+

An AI assistant rides alongside every session, suggesting next steps and adapting to the situation in real time.

+
+
+
+
</>
+
+

Automatic Documentation

+

Every session generates professional ticket notes and pushes them directly to your PSA. No more writing notes by hand.

+
+
+
+
>>
+
+

Knowledge That Compounds

+

AI analyzes completed sessions and proposes new Flows automatically. Your knowledge base grows with every ticket resolved.

+
+
+
+ + +
+

How It Works

+
+
+
1
+

Build a Flow

+

Capture your team's troubleshooting processes as decision trees

+
+
→
+
+
2
+

Run a Session

+

Engineers follow the Flow with AI copilot guidance

+
+
→
+
+
3
+

Auto-Document

+

Session notes are generated and pushed to your PSA

+
+
→
+
+
4
+

Learn & Improve

+

AI proposes new Flows from sessions automatically

+
+
+
+ + +
+ Works with: + ConnectWise PSA + + Autotask + + Halo PSA + + Slack + + Teams + + Email +
+ + +
+
resolutionflow.com
+
Free trial available — no credit card required
+
+ +
+
+ + diff --git a/docs/marketing/resolutionflow-one-pager-print.pdf b/docs/marketing/resolutionflow-one-pager-print.pdf new file mode 100644 index 00000000..ab5c80b4 Binary files /dev/null and b/docs/marketing/resolutionflow-one-pager-print.pdf differ diff --git a/docs/marketing/resolutionflow-one-pager.html b/docs/marketing/resolutionflow-one-pager.html new file mode 100644 index 00000000..33f4ddd2 --- /dev/null +++ b/docs/marketing/resolutionflow-one-pager.html @@ -0,0 +1,487 @@ + + + + + +ResolutionFlow — One Pager + + + +
+ + +
+
+ + + + + + + + + + + + + + + + +
ResolutionFlow
+
+
resolutionflow.com
+
+ + +
+

Stop Reinventing Fixes.
Build a Knowledge Engine.

+

ResolutionFlow gives MSP engineers guided troubleshooting flows, AI-assisted resolution, and auto-generated ticket documentation — so your team resolves faster and never loses tribal knowledge.

+
+ + +
+
+

The Problem

+
    +
  • Senior techs solve the same issues from memory — juniors start from scratch every time
    • +
  • Ticket notes are inconsistent, incomplete, or missing entirely
    • +
  • Tribal knowledge walks out the door when people leave
    • +
  • No standard process means unpredictable resolution times
    • +
+
+
+

The ResolutionFlow Solution

+
    +
  • Decision-tree Flows capture your best engineers' proven troubleshooting paths
    • +
  • AI copilot guides techs step-by-step and suggests next actions in real time
    • +
  • Session documentation is auto-generated and pushed straight to your PSA
    • +
  • Knowledge Flywheel turns every session into a potential new Flow
    • +
+
+
+ + +
Key Capabilities
+
+
+
//
+

Guided Flows

+

Build troubleshooting, project, and maintenance flows. Engineers follow proven paths instead of guessing.

+
+
+
AI
+

FlowPilot AI

+

AI copilot rides alongside the engineer — suggests options, explains context, and adapts to the situation.

+
+
+
</>
+

Auto Documentation

+

Every session generates professional ticket notes. Export as Markdown, HTML, PDF, or push directly to your PSA.

+
+
+
>>
+

Knowledge Flywheel

+

AI analyzes completed sessions and proposes new Flows automatically. Your knowledge base grows with every ticket.

+
+
+
<>
+

PSA Integration

+

Link sessions to tickets, pull client context, push notes — all without leaving ResolutionFlow.

+
+
+
*
+

Team & RBAC

+

Multi-tenant teams with role-based access. Admins, engineers, and viewers — each sees what they need.

+
+
+ + +
+
How It Works
+
+
+
1
+
Build a Flow
+

Create decision trees from your team's best troubleshooting processes

+
+
+
2
+
Run a Session
+

Engineer follows the Flow with AI copilot guidance on every step

+
+
+
3
+
Auto-Document
+

Session notes generated and pushed to your PSA ticket automatically

+
+
+
4
+
Learn & Improve
+

AI proposes new Flows from sessions — your knowledge compounds

+
+
+
+ + +
+
+

Integrations & Compatibility

+
+ ConnectWise PSA + Autotask (Coming Soon) + Halo PSA (Coming Soon) + Slack + Teams + Email + PDF / Markdown Export +
+
+
+

See It In Action

+

Book a 15-minute demo and see how ResolutionFlow transforms your team's troubleshooting.

+ +
Free trial available - No credit card required
+
+
+ +
+ + diff --git a/docs/marketing/resolutionflow-one-pager.pdf b/docs/marketing/resolutionflow-one-pager.pdf new file mode 100644 index 00000000..97b0548c Binary files /dev/null and b/docs/marketing/resolutionflow-one-pager.pdf differ