Guide: Building End-to-End Applications with OpenHands Agents

guides/20260531_end_to_end_openhands.md

@@ -0,0 +1,188 @@
+# Building End-to-End Applications with OpenHands Agents
+
+OpenHands is most useful when it’s doing more than isolated edits.
+
+For full-stack work, the real win is using it across the whole path from backend logic to frontend integration, testing, and deployment. That turns it from a coding helper into a development workflow engine.
+
+This guide shows how to think about building end-to-end applications with OpenHands agents.
+
+## The full-stack workflow
+
+A complete application usually has four layers:
+
+1. **Backend** — APIs, business logic, data access
+2. **Frontend** — user interface and interaction
+3. **Integration** — how the frontend and backend talk
+4. **Delivery** — tests, packaging, deployment
+
+OpenHands can help at each layer if the task is scoped clearly.
+
+## 1. Backend development with OpenHands
+
+The backend is a good fit when you need to:
+
+- add API routes
+- refactor service logic
+- update database access code
+- add validation
+- fix authentication or authorization behavior
+
+### Good backend task prompt
+
+> Update the `/api/projects` endpoint so it returns only projects owned by the current user. Add a regression test and do not change unrelated endpoints.
+
+That kind of task gives the agent a concrete target and a verification path.
+
+## 2. Frontend integration strategies
+
+OpenHands can help when the frontend needs to connect to a backend service.
+
+Typical tasks:
+
+- update API calls
+- wire up forms
+- handle loading and error states
+- adjust component state
+- align UI with backend changes
+
+### Best practice
+
+Keep the contract between frontend and backend explicit.
+
+For example:
+
+- define request/response shape clearly
+- keep API naming consistent
+- add tests or snapshots where possible
+- avoid changing the UI and API at the same time unless necessary
+
+## 3. Full-stack architecture patterns
+
+When building end-to-end applications, some architecture patterns make agent work easier.
+
+### Pattern: thin frontend, clear backend
+
+- frontend handles presentation
+- backend owns business logic
+- shared contracts define data shape
+
+This is usually easier for agents to reason about than a highly coupled design.
+
+### Pattern: feature-scoped modules
+
+Group code by feature instead of by layer when possible.
+
+That can make it easier to update everything needed for a single workflow.
+
+### Pattern: explicit service boundaries
+
+If the app depends on multiple services, document the boundaries clearly so the agent doesn’t guess.
+
+## 4. Code generation workflows
+
+OpenHands can speed up code generation, but the important part is controlling the shape of the output.
+
+Use it to:
+
+- create boilerplate
+- scaffold new endpoints
+- generate forms and handlers
+- draft tests
+- update documentation
+
+### Avoid
+
+- huge uncontrolled code generation
+- changing architecture without review
+- letting generated code go untested
+
+The best use of OpenHands is still disciplined engineering.
+
+## 5. Testing and deployment
+
+End-to-end work is not done until it is tested and ready to ship.
+
+### Testing checklist
+
+- unit tests for business logic
+- integration tests for API behavior
+- UI tests or snapshots if relevant
+- build validation
+- lint/format checks
+
+### Deployment checklist
+
+- confirm environment variables
+- verify build artifacts
+- review runtime dependencies
+- check routes and services
+- validate the deployed app before merging
+
+OpenHands is strongest when the workflow includes verification, not just code output.
+
+## A simple end-to-end example
+
+Imagine building a task-tracking app.
+
+### Backend
+
+- create `/api/tasks`
+- store tasks in the database
+- add validation
+- return normalized JSON
+
+### Frontend
+
+- build a task list component
+- add a task form
+- show loading and error states
+- wire form submission to the API
+
+### Testing
+
+- verify task creation
+- verify task listing
+- ensure invalid input is rejected
+
+### Deployment
+
+- check build passes
+- deploy to staging
+- verify the app works in the target environment
+
+OpenHands can help across each of those steps if the work is split clearly.
+
+## Troubleshooting tips
+
+If the workflow gets messy, usually one of these is happening:
+
+- the task is too large
+- the repo structure is unclear
+- the backend contract is vague
+- tests are missing
+- the environment is unstable
+
+### Fixes
+
+- split the task into smaller pieces
+- document the API contract
+- add the most important tests first
+- keep the environment reproducible
+- review the diff before expanding scope
+
+## Best practices for full-stack AI development
+
+- Keep frontend/backend boundaries clear.
+- Add tests early.
+- Use feature-scoped tasks.
+- Don’t mix unrelated refactors into one PR.
+- Validate the app in the same environment where it runs.
+- Keep the agent focused on one deliverable at a time.
+
+## Final takeaway
+
+OpenHands works best for full-stack development when the task is structured well.
+
+The agent can help with backend code, frontend integration, tests, and deployment support — but only if you make the workflow explicit. If you treat the app as a series of smaller, connected tasks instead of one giant blob, you get much better results.
+
+That’s the key to end-to-end work with agents: clear boundaries, clear tests, and clear delivery.