Refactoring Guide

M
Written By Melih SünbülLast updated 5 months ago

This is a hands-on, step-by-step guide for migrating a V1 (generic_app) project to the current Lex App framework. Work through it in order — each part builds on the previous one.

If you're starting a new project from scratch, skip this entirely and follow the TeamBudget Tutorial instead.

Before You Start

Make sure you have:

  • A working V1 project that you want to migrate
  • lex-app installed (pip install lex-app)
  • Familiarity with the V1 codebase (model files, generic_app imports)

Back up your database before starting. Always have a restore point before making sweeping changes to your codebase.

The Series

  1. Part 1 — Project Structure & Imports — restructure your project into ETL folders and update all imports from generic_app to lex.*
  2. Part 2 — Models & Fields — convert your model base classes and clean up legacy fields
  3. Part 3 — Calculations — migrate ConditionalUpdateMixin to CalculationModel
  4. Part 4 — Lifecycle Hooks — replace UploadModelMixin with explicit @hook decorators
  5. Part 5 — Logging & Permissions — upgrade CalculationLog to LexLogger and ModificationRestriction to permission_* methods

How Long Does It Take?

Project Size

Estimated Time

Small (< 10 models)

1–2 days

Medium (10–30 models)

3–5 days

Large (30+ models)

1–2 weeks

Quick Reference

Keep these open while you work:

Was this helpful?

Your feedback shapes what we write next.