Committing before moving to local disk
This commit is contained in:
chihlasm
188
PROGRESS.md
Normal file
188
PROGRESS.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user