Project Structure
=================

MCCS is a sizeable project, and as such, it can be difficult to navigate to new developers. This section aims to provide a high-level overview of the code structure. 

First, the source code is spread over several repositories, over different layers:

* `ska-low-mccs` - main repository containing MCCS devices like the antennas, controller, station, etc.
* `ska-low-mccs-spshw` contains  Local Monitoring and Control (LMC) devices like tiles, sps stations, subracks, etc. 
* `ska-low-mccs-calibration` defines the station calibration subsystem for the SKA-Low telescope. It is part of the MCCS subsystem.
* `ska-low-mccs-common` provides a Python package of functionality shared across MCCS repositories.
* `ska-low-mccs-daq` integrates the data acquisition subsystem in MCCS. This is currently split over several repos (see also `ska-low-mccs-daq-interface`) but will be reduced to one in the future.
* `ska-low-mccs-pasd` contains the MCCS prototype for the Power and Signal Distribution (PaSD) of the SKA-Low radio telescope's field stations.

MCCS Repo Structure
-------------------

The main repo is split similarly to other projects: source code can be found in the `src/ska_low_mccs` directory, documentation in `docs` and tests in `tests`.
Additionally, it's important to note early that this project is meant to run in a k8s cluster, so there are a few directories related to that. 
Charts are found in `charts/ska-low-mccs` and the helmfile in `helmfile.d` (more on this, in the k8s part of the tutorial). 
Additionally, there is a directory for scripts (`scripts`), Jupyter notebooks (`notebooks`), demos (`demos`), and a few other hidden directories, as well as configuration files for the project.

The source code is further divided into directories, some contain devices, and others are auxiliary.

Device directories:

* Antenna (deprecated): a simple device that represents a single antenna in the SKA-Low telescope. Deprecated, will be removed in the future.
* Controller: this device provides the highest-level overview of the MCCS system and is one of two entry points for a user along with MccsSubarray.
* Station: is responsible for coordinating the functionality of each hardware within a Field node (antennas are grouped in 'physical 
  stations' called Field nodes, which include antennas, tiles, subracks and power supply units).
* Tiles: this device is found in the `ska-low-mccs-spshw` directory and it controls the TPM (tile processing modules) and data streams.
* Station Beam: This device is responsible for scanning beams for a single station involved in a subarray. It is directed by the subarray's 
  SubarrayBeam device. Note that, in general, more than one StationBeam device may be driving a station because stations can have multiple beams and 
  may be involved in observations for multiple subarrays.
* Station Calibrator
* Subarray:  A portion of telescope resources allotted for operation independently of other subarrays. All telescope observations are driven through 
  subarrays. Note that stations may be shared between more than one subarray at a time, dividing station resources between them.
* Subarray Beam:  Telescope observations with a subarray are enacted by means of the subarray's SubarrayBeam device. This device then steers the 
  stations involved in the observation by means of their StationBeam devices.
* Transient Buffer
* Calibration Store

Additionally, there is the calibration solver directory and the schemas folder.

Tango Device Structure
----------------------

Each device directory contains several Python files, which are used to define the device's functionality:

* `device.py`: This file broadly contains the Tango layer for the device, defining its attributes, commands, and other functionalities.
* `component_manager.py`: This file broadly contains the functionality/business logic.
* `health_model.py` and `health_rules.py`: used to define the device's health state.
* Additional, device specific, files are also present. These will be covered in the device-specific tutorials/explanations.

The device file and component manager file are often similar in structure, as attributes and commands that interact with hardware are passed through the component manager.
The Pytango device is usually defined in a class, within the `device.py` file. Init routines, attributes, commands and callbacks are often separated by comment tags.
The component manager will also be defined in a class, which will contain methods corresponding to some of the commands and attributes defined in the device but will not share the same structure.