<aside> 🧑‍💻 This documentation is part of the Technical Kick-start Collection. If you’re a developer interested in contributing to Thea, or just looking to understand how Thea works on a deeper level, then I’d highly recommend reading through this collection.

</aside>

Code Architecture

Thea’s back end, written in Go, is responsible for essentially every aspect of Thea - in that sense, the front end is functioning as a ‘thin client’, containing no real functionality or logic aside from presentation-logic.

Thea consists of three main layers:

• API Translation

  The API layer is what is interacted with by incoming requests from clients. This layer itself should not track any state, instead, relying on calling in to core or Thea services to find the relevant state for the response.

  WebSocket API

  REST API

• Thea Core

  The Core layer is the glue-code that handles interaction between multiple different services. This code exists outside of service packages, typically because the code is general and re-usable. Multiple services will often make use of this ‘common’ code.

  Metadata Scraping

  TMDB Searching

  Media Management

• Services

  Finally, the service layer, which underpins all of Thea’s functionality. “Service” is a pretty loaded term, so Thea defines some expectations of what services should do:

  • Have internal state that is siloed from the rest of the application.
  • Be concerned with ‘one aspect’ of the Thea experience.
  • Emit and listen for external changes using events.
  • Process long-running or blocking tasks asynchronously, often using a queue structure.
  • Track and allow resolution of troubles due to errors when performing asynchronous tasks.
  • Persistent state, such as writing to database or caching information in the servers file system.
  • Data modified or created by a service should be complete. A service should not ‘hand off’ data to other services. If subsequent processing is required, then the complete data should be persisted (e.g., in the database), and the id of that data sent to the service via the event bus.

  Download Service

  Ingest Service

  Transcode Service

  Activity Service

Inter-Service Communication

Thea services should try to avoid calling in to each other as much as possible. If some logic needs access to data from multiple services, then it’s positioning inside a service should be re-considered; Thea core is likely a better place for it to live.

However, Thea services often needs to be aware of outside changes by way of communication; Thea’s solution to this is a centralized event bus that services can use to both emit and subscribe to events. The events a particular service emits/subscribes to are documented in each service.

Event Etiquette

Events should not contain data structures, rather opting to use the id of the data that exists in some persistent data store. If you find yourself needing to share data between two services, then reconsider whether:

• Should the data you’re sharing be shared?
• Could the logic that needs the shared data be moved outside of the service?
• Would the data be better placed in a persistent data store first, before sharing it’s id?

Most of the time, needing to share data itself is a sign that your inter-service communication is flawed - typically due to one service doing too much. A good way to detect this is to look out for branching flows in your service code; different behavior depending on the external state is often a sign that the service is trying to handle too many states.