Architecture
========================

This document describes the architecture of CoCalc in Kubernetes.
It's helpful to know a bit about the services it is composed of, but
it's not necessary to understand everything in every detail.

Here is a high-level overview:

- :ref:`database`: holds all the **information** about users, projects, and everything else.
- :ref:`Storage <storage>`: holds all **files** edited and published by users via their projects.
- :ref:`Hub services <hubs>`: the entry points for users and projects from the internet. They are responsible for authentication, authorization, and routing.
- :ref:`Project pods <project>`: the actual containers running the user projects. These project pods are managed by a set of microservices called
- :ref:`manage`, which are responsible for starting, stopping, and monitoring projects.

In a nutshell, this is what they're doing:

- A couple of services will be running in pods in the kubernetes cluster → :ref:`hubs`, :ref:`static` and :ref:`manage`,
- Some of them will talk to the database → :ref:`database`,
- Some have endpoints, which are exposed via :term:`Ingress` configuration files → :ref:`static` and :ref:`hubs`,
- A few services will dynamically create and delete pods (aka "CoCalc Projects") inside that cluster → :ref:`manage`,
- and many of these pods will mount directories of a shared filesystem → :ref:`architecture-storage`.


.. toctree::
  :hidden:
  :maxdepth: 1

  architecture/static
  architecture/hubs
  architecture/manage
  architecture/storage
  architecture/projects
  architecture/project-nodes
  architecture/prepull
  architecture/ssh-gateway
  architecture/datastore

After you have a basic understanding of the architecture, you can
continue :doc:`preparing your cluster <setup>`.