# Routing

Shipclojure uses [reitit](https://github.com/metosin/reitit) for both frontend and backend routing because it is the fastest router in the clojure ecosystem and it is data oriented (you can represent your routes as vectors):

```clojure
(def routes ["/" {:handler (fn [req] {:status 200 :body "Hello"})}])
```

> Fair warning: Reitit is a bit hard to grasp as first but no worries since most of the middleware and hard wiring is done for you.

## Swagger

Shipclojure uses [swagger](https://swagger.io/) for documentation, if you have your server running, visiting <http://localhost:8080/api> should show you the swagger documentation for all routes: api, web routes & websocket.

## Routes

The routes are split into 3 categories:

1. REST api routes: [api.clj](https://github.com/shipclojure/shipclojure/blob/main/src/clj/saas/web/routes/api.clj)
2. Websocket routes: [websocket.clj](https://github.com/shipclojure/shipclojure/blob/main/src/clj/saas/web/routes/websocket.clj)
3. Frontend routes (mix of static pages rendered on the backend and frontend only routes): [common/routes.cljc](https://github.com/shipclojure/shipclojure/blob/main/src/cljc/saas/common/routes.cljc)

How to know which frontend routes are server rendered and which are frontend only: Frontend routes will have a `:view` while backend routes will have the normal syntax of `:get/:post (fn [req] (render-page req))`.

Example

```clojure
(def routes
["" #?(:clj {:get root}) ;; the default empty html that just renderes on the frontend
 ["/" (merge {:seo/title "Home"
              :seo/description "The SaaS boilerplace for your next project"
              :name ::index}
              ;; Rendered on the backend
             #?(:clj {:get layout/landing-page}))]
 ["/verify" (merge
              {:name ::verify
               :seo/title "Verify your account"
               :seo/description "Finish creating account by confirming your email"}
              ;; Rendered frontend only
              #?(:cljs {:view verify/verify-email-page}))]])
```

## Middleware

The shipclojure router has middleware already setup for your convenience.

See all the middleware here: [handler.clj](https://github.com/shipclojure/shipclojure/blob/main/docs/src/clj/saas/web/handler.clj)

Here is the [documentation for reitit middleware](https://github.com/metosin/reitit/blob/master/doc/ring/default_middleware.md)

## Websockets

Websockets use [ring.websocket](https://github.com/ring-clojure/ring/wiki/WebSockets). Read the documentation to understand how it works.


---

# Agent Instructions: 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://shipclojure.gitbook.io/shipclojure-docs/backend/routing.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.