← cd ~/blog

From MVP to Enterprise - The Evolution of Nexus and the Path Forward

January 3, 2025|9 min read
#nexus#architecture#devops#lessons

Introduction

Every significant software system has a creation story. It begins as a spark--usually frustration with existing tools--and evolves through countless decisions, refactors, and course corrections into something that scales across an entire organization.

Looking at Nexus's git history of 294 commits, we can see this journey. It's not a straight line from concept to perfection. Instead, it's a winding road with pivotal moments, strategic decisions, and hard-won lessons.

In this final post of our three-part series, we'll trace Nexus's evolution, understand the decisions that shaped it, examine the current state of in-development features, and explore the future roadmap that will take it from a regional tool to an enterprise platform.

The Genesis: Identifying the Problem

Nexus wasn't built because management wanted a new IT system. It was built because people were drowning in spreadsheets.

Imagine this scenario (which was surely the reality):

  • Sales team has a spreadsheet with contract information
  • Drafting team has a different spreadsheet with drafting status
  • Engineering has another spreadsheet with review notes
  • Field operations has yet another spreadsheet with construction schedules
  • Management tries to consolidate all these into a master spreadsheet

By the time the data flows from spreadsheet A to spreadsheet B to spreadsheet C, it's outdated. A drafter finishes a lot but the status doesn't reach the field operations team for three days. Meanwhile, the manager has already printed a report from the old data and made decisions based on stale information.

Nexus was built to solve this: a single source of truth for all project data, updated in real-time, with proper access controls so everyone sees what they need to see.

The MVP Phase: Foundation First

The MVP focused on the two most critical workflows:

  1. EPC (Engineering & Permitting Center)
  2. FOSC (Field Operations Schedule Center)

Why these two? Because they represent the longest and most complex workflows in home construction. If you can track these, everything else becomes manageable.

The MVP likely had:

  • Basic lot creation and status tracking
  • Simple permission system (just read vs. write)
  • Ability to assign work to team members
  • Basic filtering and search

Early Challenges: Learning from Reality

Once the MVP went into actual use, reality hit. The git history shows several classes of fixes:

1. Permission Complexity

Permissions turned out to be more complex than expected. Users needed different views depending on their role. Some users should see certain lots, some shouldn't. Some users should be able to edit certain fields, not others.

The system evolved from a binary "can read/can't read" model to a nuanced system where:

  • Role 210 (EPC Viewer) sees all EPC lots
  • Role 211 (EPC Editor) sees all EPC lots AND can edit
  • Role 213 (EPC Super User) sees all EPC lots, can edit, AND can send emails
  • Role 220 vs 221 has a similar structure for FOSC

This granularity didn't appear in the original design. It emerged from usage feedback.

2. Dashboard Evolution

The dashboard went through extensive development. Why? Because managers wanted to see different things than initially anticipated:

  • Not just "what stage is this lot in" but "how long is it taking"
  • Not just "is it finished" but "is it on track"
  • Not just individual lots but aggregated metrics and trends

The cycle-time analysis required going back through the data model and ensuring every state transition recorded timestamps. This wasn't in the initial design.

3. Home Siting and Field Operations

Home siting--the physical act of preparing the land and surveying the home location--turned out to be more complex than initially modeled. The system was extended to track:

  • Who is the surveyor
  • When is home siting scheduled
  • What are the special requirements for this lot's location
  • How does this affect construction timeline

The Major Turning Point: IHMS Integration

A significant architectural shift occurred when it was time to integrate with the legacy system.

The Challenge

Eagle Construction had an existing IHMS (Internal Home Management System) containing:

  • Historical project data
  • Vendor information (master list of contractors, subcontractors)
  • Construction timelines
  • Financial information
  • Other administrative data

The options were:

  1. Migrate Everything - Rewrite all data from the old system into Nexus (expensive, risky, business disruption)
  2. Start Fresh - Abandon IHMS and don't use any of its data (wasteful, loses institutional knowledge)
  3. Bridge the Systems - Keep IHMS for what it does well, augment with Nexus (pragmatic, risky if not done right)

The developers chose option 3.

The Implementation

async def connect_ihms_db():
    # Opens MySQL connection to legacy database
    # Allows schema mapping between old and new systems

The IHMS schema files show careful mapping:

class IHMSTableVendorMaster(BaseModel):
    company_code: str
    vendor_number: str
    vendor_name: Optional[str]
    address1: Optional[str]
    phone_number: Optional[str]
    # ... 50+ fields

This allowed Nexus to:

  • Pull vendor master data from IHMS for dropdowns ("assign to contractor X")
  • Use IHMS construction start dates in calculations
  • Reference IHMS superuser IDs for permissions
  • Generate reports that combine old and new data

Production Deployment: Real-World Constraints

Multi-Environment Support

Environment files:
.env.dev   - Development (localhost, verbose logging)
.env.test  - Testing (isolated test database)
.env.prod  - Production (hardened, optimized)

Docker Deployment

FROM python:3.11
WORKDIR /app/backend
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]

Dockerization ensured:

  • The exact same code runs locally and on GCP
  • Developers don't have "but it works on my machine" issues
  • Scaling requires just spinning up more containers

Cloud Deployment on GCP

The system is deployed on Google Cloud Platform VMs with:

  • Specific zones for free-tier instances
  • Network tag configuration for firewall rules
  • External IP management
  • Volume persistence

Current State: Stable and Scaling

Looking at the system holistically, Nexus has reached a state of stable maturity:

  • Core workflows are solid: EPC and FOSC are thoroughly tested and used daily
  • Permissions are well-defined: Role system has evolved through real usage
  • Integration is working: IHMS bridge is functional and in use
  • Dashboard is operational: Managers are using it for decision-making
  • Deployment is automated: Docker enables quick updates and rollbacks

The system is handling:

  • 7,272 lines of Python backend code
  • 18,500 lines of TypeScript/React frontend code
  • ~1,100 lines of database schema definitions
  • ~38 Python files organized into routers
  • ~181 TypeScript files organized into features
  • Multiple external integrations (MongoDB, MySQL, IHMS, Email, Socket.IO)

The Future Roadmap

1. Advanced Analytics

  • Predictive analytics: "Based on current pace, lot X will be ready on Y date"
  • Trend analysis: "Our cycle times are improving 5% month-over-month"
  • Bottleneck detection: "Permitting at County Z is 40% slower than average"
  • Resource allocation: "Drafter A is overloaded, Drafter B has capacity"

2. Mobile App

Field supervisors need to check lot status from the construction site, not just from an office computer.

3. Integration with More External Systems

Future integrations might include:

  • Accounting system: Linking home costs to project data
  • Mapping/GIS: Showing properties on a map with status overlays
  • Document management: Storing permits, plans, certifications within Nexus
  • Vendor portals: Allowing contractors to update progress directly

4. Expanded Department Coverage

  • Sales Department: Full CRM functionality
  • Finance: Cost tracking and budget management
  • Warranty: More sophisticated warranty issue tracking
  • HR: Crew management and scheduling

5. UI Polish

The TODO items are telling:

  • Edit the colors of loading spinner
  • LoginForm component - refactor it, separate the business logic
  • Better error displaying on LoginForm (show toast)
  • New lot page - responsive card layout

These are UX refinements, not feature work. The system is stable enough that time can be spent on polish.

Lessons Learned

1. Start with the Core Problem

Nexus didn't start by trying to build a "perfect" system. It started by solving the most acute pain point: replacing fragmented spreadsheets with centralized data.

2. Embrace Pragmatism

The decision to integrate with IHMS rather than replace it shows pragmatism. Perfect is the enemy of good. A system that works with existing data beats a system that's architecturally purer but requires massive migration.

3. Iterate Based on Reality

The permission system, the dashboard, the field operations features--all evolved based on actual usage. The developers weren't coding in a vacuum. They were responding to feedback from users who understood the business.

4. Invest in Architecture, but Don't Over-Engineer

The database structure is well-designed, but not overly complex. The routers are organized, but not excessive. The code is pragmatic--it solves problems, it doesn't try to solve hypothetical future problems.

5. Use Tools That Enable Rapid Development

Python with FastAPI, React with TypeScript, Docker for deployment--these choices enable iteration speed. The developers aren't fighting their tools; the tools enable them.

6. Automate Deployment

Docker and docker-compose enable safe, repeatable deployments. This means improvements can be released frequently without fear. The commit history shows roughly one significant update every few days--that's only possible with reliable deployment infrastructure.

Conclusion: A System Built by Users, for Users

What impresses most about Nexus isn't any single technical innovation. It's the alignment between architecture and reality. The system's structure reflects how the business actually works, not how some consultant thought it should work.

The path forward is clear:

  • Polish the current UI
  • Add more sophisticated analytics
  • Expand to other departments
  • Integrate with more external systems
  • Consider mobile applications

But the foundation is solid. Nexus has proven it can:

  • Centralize data from fragmented sources
  • Integrate with legacy systems
  • Scale to enterprise levels
  • Support complex workflows across multiple departments
  • Enable real-time collaboration

The journey from the first commit to version 1.0.0 took 294 commits. Along the way, architecture evolved from conceptual to battle-tested, features were added based on real needs, permissions were refined as organizational structure clarified, and deployment became automated and repeatable.

For anyone building complex business systems, Nexus is a study in pragmatic software engineering: solving real problems, learning from usage, iterating rapidly, and building systems that work in the real world--not just in theory.

This concludes the three-part series on Nexus. Part 1 covered the architectural foundation. Part 2 covered department-specific features. Part 3 covered the evolution and future.