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](./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**:

   ```bash
   cd backend
   docker-compose up -d
   ```

2. **Set up Python environment**:

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

3. **Configure environment**:

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

4. **Run database migrations**:

   ```bash
   alembic upgrade head
   ```

5. **Start the development server**:

   ```bash
   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)