> For the complete documentation index, see [llms.txt](https://medusa-ui.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://medusa-ui.gitbook.io/docs/hydra/concept.md).

# Concept

The key goal of Hydra is to elevate Medusa from a UI framework to a modular micro-frontend architecture.

## What does that mean?

In practice, it should be possible to:

* Divide up the apps with Medusa frontend into modular microservices and deploy and maintain them completely separately
* Have menu items and links react to the availability of said microservices: More menu items appear when new services come up, links get marked as disabled when functionality is down when a direct URL is hit a clean redirect or error page is shown
* Have the various microservices share a security context

And Hydra should ensure this all happens seamless (literally, we should not be able to tell the difference from a user perspective)

This means Hydra becomes a critical component - if it goes down, so does all access to all front-end services. As such, it should be developed with high availability in mind.

## How would this work?

We combine a few technologies and prep them for easy usage (as in, only minor configuration required).

Hydra uses Spring Cloud Gateway to serve as a reverse proxy with load balancing capabilities. It is the entry point for our users and abstracts away the microservices behind it.

### Concrete flow

* Hydra boots up, URL becomes available ([https://sample.com](https://sample.com/))
* Frontend microservices boot up, register themselves with Hydra as available (/order is now available at IP x.x.x.x:yyyy). Registration happens akin to 'Service Discovery'.
* Hydra makes these new routes available to the user (<https://sample.com/order> is provisioned). Any route has a 'fallback'.
* Hydra keeps a long-running, recoverable WebSocket connection open to the frontend services' to verify availability. The instant the socket connection closes, the URL is deprovisioned.

### Concrete flow for the user

* User connects to a URL via Hydra (<https://sample.com/order>)
* User is not yet logged in, so is redirected to login (<https://sample.com/login>)
* User logs in, an OAuth2 JWT token gets added to a cookie, the user is directed back to the original URL (<https://sample.com/order>)
* Hydra forwards said request to the correct frontend microservice together with the JWT cookie value
* Frontend microservice can ask Hydra for the key to validate incoming tokens.

As long as Hydra is up, services can go up/down without the user noticing. If they try to access a route that is not provisioned, they hit the fallback.

### Dynamic menus

Each health check socket is also a communication point to transfer an overview of available services to all front-end services. As services come online and go offline, the internal cache of each frontend service gets kept up to date. This internal cache can be called to build menus dynamically.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://medusa-ui.gitbook.io/docs/hydra/concept.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.