resolutionflow/PROGRESS.md

Project Apoklisis - Development Progress

Last Updated: January 23, 2026 Current Phase: Phase 1a Backend API - COMPLETE

---

Project Overview

Building a troubleshooting decision tree web application for MSP engineers. The app allows creating, managing, and navigating through decision trees for common IT support scenarios.

Tech Stack:

• Backend: Python FastAPI + SQLAlchemy 2.0 (async) + PostgreSQL
• Frontend: React + Tailwind (not started)
• Hosting: Render (dev) / Railway Pro (production)

---

Apoklisis Development Progress

📚 Reference: See CLAUDE-SETUP.md for available development tools and usage guidelines

Completed Work

Phase 1a: Backend API (COMPLETE)

All backend components have been created following 02-TECHNICAL-ARCHITECTURE.md exactly.

Project Structure Created

backend/
├── alembic/                    # Database migrations
│   ├── versions/
│   │   └── 001_initial_schema.py
│   ├── env.py
│   └── script.py.mako
├── app/
│   ├── api/
│   │   ├── endpoints/
│   │   │   ├── auth.py         # Authentication (register, login, refresh, logout)
│   │   │   ├── trees.py        # Trees CRUD + search
│   │   │   └── sessions.py     # Sessions + export (md, txt, html)
│   │   ├── deps.py             # Auth dependencies (get_current_user, role checks)
│   │   └── router.py           # Main API router
│   ├── core/
│   │   ├── config.py           # Settings via pydantic-settings
│   │   ├── database.py         # Async SQLAlchemy engine + session
│   │   └── security.py         # JWT creation/validation + bcrypt
│   ├── models/
│   │   ├── user.py             # User model (UUID, email, role, team_id)
│   │   ├── team.py             # Team model
│   │   ├── tree.py             # Tree model (JSONB tree_structure)
│   │   ├── session.py          # Session model (path tracking)
│   │   └── attachment.py       # Attachment model (file uploads)
│   ├── schemas/
│   │   ├── user.py             # User Pydantic schemas
│   │   ├── token.py            # JWT token schemas
│   │   ├── tree.py             # Tree request/response schemas
│   │   └── session.py          # Session schemas + export
│   └── main.py                 # FastAPI application entry point
├── alembic.ini
├── docker-compose.yml          # PostgreSQL 16 container
├── requirements.txt
├── .env.example
└── README.md

Database Schema (5 tables)

• users - User accounts with roles (admin, engineer, viewer)
• teams - Team groupings for users
• trees - Decision trees with JSONB structure, versioning, categories
• sessions - Troubleshooting sessions with path tracking
• attachments - File attachments for sessions

API Endpoints Implemented

Method	Endpoint	Description
POST	/api/v1/auth/register	User registration
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 (client-side)
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
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 (add decisions)
POST	/api/v1/sessions/{id}/complete	Mark session complete
POST	/api/v1/sessions/{id}/export	Export session (md/txt/html)

Key Technical Decisions

• UUIDs: All primary keys use PostgreSQL gen_random_uuid()
• JSONB: Tree structures and session paths stored as JSONB
• JWT Auth: 15-minute access tokens, 7-day refresh tokens
• Password Hashing: bcrypt with cost factor 12
• Full-text Search: PostgreSQL to_tsvector on tree name/description
• Soft Deletes: Trees use is_deleted flag, not hard delete
• Async: All database operations use async SQLAlchemy

---

How to Run the Backend

1. Start PostgreSQL:

   cd backend
   docker-compose up -d
   

2. Set up Python environment:

   python -m venv venv
   venv\Scripts\activate        # Windows
   # source venv/bin/activate   # Linux/Mac
   pip install -r requirements.txt
   

3. Configure environment:

   cp .env.example .env
   # Edit .env if needed (defaults work for local dev)
   

4. Run database migrations:

   alembic upgrade head
   

5. Start the development server:

   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   

6. Access API docs: http://localhost:8000/api/docs

---

What's Next

Phase 1b: Pre-built Trees (Not Started)

• Create seed data script with 5 troubleshooting trees from TS-EXAMPLES.md:
  1. FSLogix Profile Issues
  2. Citrix VDA Registration
  3. File Share Access Problems
  4. AD Replication Issues
  5. Password Reset/Account Lockout

Phase 2: Frontend (Not Started)

• React application with Tailwind CSS
• Tree navigation interface
• Session management UI
• Admin panel for tree creation/editing

---

Important Files to Reference

File	Purpose
02-TECHNICAL-ARCHITECTURE.md	Full technical spec (database schema, API endpoints)
05-QUESTIONS-AND-ACTION-ITEMS.md	Design decisions and priorities
TS-EXAMPLES.md	5 example troubleshooting trees to implement
backend/README.md	Backend setup instructions
backend/.env.example	Environment variable template

---

Notes for Next Session

• Backend code is written but not yet tested - need to run and verify
• No seed data created yet - trees table is empty
• Frontend work has not started
• Single-user focus for MVP (team features are in schema but low priority)