UX Research

UX Research & User Flows

UX scoping document detailing target user profiles and mapping key user journeys to backend server API routes.

---

1. Personas

Persona 1: Alex — The Solo Developer ("Fast & Pragmatic" Profile)

• Profile: Independent developer or freelancer building side-projects and MVPs.
• Needs: Instant conversion and deployment without complex infrastructure setup.
• Pain Points: Time wasted on manual setups; lack of straightforward tools to roll back quickly when a build breaks.
• Typical Usage: Uses the CLI or web UI to connect a personal repository, run a quick conversion test, and revert immediately if the output is unstable.

Persona 2: Sarah — The Tech Lead ("Control & Compliance" Profile)

• Profile: Lead developer at an SME managing a team of 6 engineers.
• Needs: Seamless integration with organization-level GitHub/GitLab, change traceability, and granular version management.
• Pain Points: Fear of side effects during legacy code migrations/conversions; need to guarantee build reproducibility.
• Typical Usage: Connects team repositories via organizational OAuth, inspects conversion logs, and oversees rollbacks when necessary.

Persona 3: Lucas — The Student / Junior Developer ("Learning by Doing" Profile)

• Profile: Computer science student or junior developer in training.
• Needs: Intuitive interface, clear error messaging on conversion failures, step-by-step onboarding guides.
• Pain Points: Intimidated by complex Git commands; overwhelmed by raw API stack traces.
• Typical Usage: Follows the complete onboarding flow, experiments with conversions on simple academic projects, and relies on the revert feature to recover from mistakes.

---

2. Main User Flows & Server Route Mapping

Flow 1: Onboarding Flow (Sign-up & First Team/Project)

User Step	Frontend Action	Called Server Route
Sign-up / Login	Sends credentials	POST /auth/register or POST /auth/login
Profile Retrieval	Loads current user profile	GET /me
Team Creation	Create team	POST /teams
First Project Creation	Submits initial project form	POST /teams/{id}/projects

Flow 2: Git Connection Flow (Team Integration & Project Link)

User Step	Frontend Action	Called Server Route
Start Integration	start OAuth flow with provider	POST /teams/{id}/integrations/{provider}/connect
Auth Callback	Provider redirects with auth state	GET /teams/{id}/integrations/{provider}/callback
Repository Selection	Fetches accessible repositories	GET /teams/{id}/integrations/{provider}/repos
Link to Project	Binds remote repo to local project	POST /projects/{id}/repo/link

Flow 3: First Conversion Flow (Initial Transformation Job)

User Step	Frontend Action	Called Server Route
Import / Source File Selection	Uploads schema file(s) or imports form repo	POST /projects/{id}/files
Conversion Configuration	Fetches supported target ORMs	GET /orms
Trigger Conversion	Launches asynchronous transformation job	POST /projects/{id}/transform
Processing Tracking & Result	Polls status / receives results (or stream via /jobs/{job_id}/stream)	GET /jobs/{job_id}

Flow 4: Revert Flow (Rollback to Previous State)

User Step	Frontend Action	Called Server Route
History Inspection	Fetches modified files history	GET /projects/{id}/history
File Versions & Diff Preview	Lists versions and previews diff against a target version	GET /projects/{id}/history/{fileId}/versions & GET /projects/{id}/history/{fileId}/diff?version={target}
Revert Confirmation	Sends rollback payload { files: [{ fileId, version }] }	POST /projects/{id}/revert
Reload Project State	Refreshes project details and file list	GET /projects/{id} & GET /projects/{id}/files