diff --git a/PROGRESS.md b/PROGRESS.md new file mode 100644 index 00000000..07846fb1 --- /dev/null +++ b/PROGRESS.md @@ -0,0 +1,188 @@ +# 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) + +--- + +## 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)