Итак, ваш первый день в офисе, вам дали доступы ко всем 15 репозиториям проекта, рассказали где что лежит, и теперь ждут от вас великих дел. Они и не подозревают, что вы уже забыли, какой карточкой открывается этаж и где стоит кофемашина.

Добро пожаловать в 50% IT-компаний вторую статью цикла про онбординг в сложную систему!

В первой части данного цикла я начала с самого верхнего слоя: посмотрела на проект как на black box, выписала основные сущности и собрала первый словарь. Это снимает первое напряжение: мозг уже не хаотично скачет от репозитория к репозиторию, а начинает искать связь между кодом и главной функциональностью. И это уже лучше, чем ничего.

Но наша цель - максимально возможное понимание всей системы за минимально возможный срок. Поэтому мы будем копать дальше.

В этой статье я продолжаю разбирать публичный проект ThemeParks и собираю repository map — карту ключевых репозиториев, их ролей и связей. Это не точная внутренняя архитектура команды, а onboarding-map по публичным данным. Цель - понять, через какие репозитории проходит основной поток данных.

К концу статьи у нас будет:

  • короткое описание ключевых репозиториев;

  • dependency matrix — таблица проверенных связей;

  • схема их вероятных взаимосвязей;

1. Доступы есть, понимания нет

Обычно новичку дают доступы ко всем репозиториям и, если повезёт, объясняют:

“Вот основной бекенд, тут фронтенд, тут сервис для проверки того-то, тут вторая версия такого-то сервиса, а этот репозиторий отвечает за генерацию клиентов. Начни с основного сервиса, потом посмотри документацию и конечно наши терабайты записей тренингов. Если установка не заведётся — поправь потом в инструкции”.

Иногда там даже есть README и часто инструкции по установке. И это уже неплохо.

Я часто замечала, что README обычно объясняет отдельный репозиторий, а не систему между репозиториями.

В итоге у новичка появляется плоский список:

  • основной бекенд;

  • фронтенд;

  • сервис для проверки того-то;

  • вторая версия такого-то сервиса;

  • генератор клиентов;

Такой список тоже нужен. Мы его составим как промежуточный артефакт. Но он не помогает начать работать из-за своей плоскости.

Это как описать сказку, просто перечислив действующих лиц - 3 поросенка, 3 домика и волк. Можно догадаться, что они будут делать, но вряд ли это будет то, что задумывал автор.

Поэтому на этом этапе я хочу перейти от списка репозиториев к карте их ролей и связей.

В моей практике это довольно переломный момент онбординга. После такой карты уже можно худо-бедно приступать к работе. Обладая знаниями словаря, что система делает в целом и где это примерно располагается, уже не такая большая проблема найти точное место в коде.

Будь ThemeParks чуть более сложен с точки зрения бизнес-логики, мы бы прошлись по его основным 2-3 сценариям и составили бы краткую документацию по ним. И у меня уже есть на примете проект где я покажу как это делать.

Помимо уже озвученного плюса repository map есть еще один важный момент - на него отлично ложится схема data flow. Это уже чуть более детализированная по данным схема потока.

Что обидно: такую схему почти никогда не дают на старте. Хотя именно она могла бы сильно сократить первые дни или даже недели онбординга. И сделать ее ничего не стоит, когда ты понимаешь систему.

Если вы разработчик и перед вами новый проект — составьте такую карту хотя бы для себя. А потом включите в пресловутую инструкцию по установке, которая, надеюсь, сработала.

2. Что получим в конце

Сегодня соберем 3 артефакта:

  • repo roles: короткое описание, какую роль играет каждый ключевой репозиторий.

  • dependency matrix: таблица проверенных связей между репозиториями и API boundary.

  • relationship map: схема, которая показывает, как репозитории связаны между собой.

В итоге после этого этапа у новичка появляется не набор репозиториев, а рабочая карта:

С такой картой уже проще открывать код: ты понимаешь не только название репозитория, но и его место в системе.

3. Про ThemeParks

В этой статье я использую публичный проект ThemeParks как тренировочный пример, и важно проговорить: я не нахожусь внутри команды ThemeParks, не знаю их внутренних договорённостей и не пытаюсь точно описать их реальную архитектуру.

В реальном онбординге этот этап обычно проще. Команда уже знает, какой репозиторий за что отвечает. Задача не в том, чтобы угадывать роли по косвенным признакам, а в том, чтобы зафиксировать это знание в понятной карте.

И раз у меня нет внутреннего контекста, я собираю рабочую гипотезу по открытым признакам:

  • описаниям репозиториев;

  • README;

  • структуре проекта;

  • публичным зависимостям;

  • названиям файлов и папок;

  • ссылкам между репозиториями.

То есть я показываю не “как устроен ThemeParks на самом деле”, а как можно думать при входе в незнакомую систему.

Наша цель — не угадать чужую архитектуру идеально. Наша цель — научиться превращать разрозненные публичные следы проекта в рабочую onboarding-map.

4. Плоский список

Начинаю с плоского списка и превращаю его в карту зависимостей, потом в рабочую карту.

В GitHub organization ThemeParks сейчас видно 8 публичных репозиториев:

Репозиторий

Рабочая роль

Почему так думаю

parksapi

probable core data / integration layer

Описан как backend library для получения live theme park data. В README сказано, что библиотека получает real-time данные: wait times, schedules, entity metadata — и powers the free API at ThemeParks.wiki.  

typelib

shared types / schema layer

Описан как ThemeParks.wiki TypeScript Type Lib. В README говорится, что пакет генерирует типы из JSON schemas и даёт runtime type validation. Поэтому на первом проходе я отношу его к слою общих типов и схем.  

ThemeParks_JavaScript

JS/TS SDK for API consumers

Описан как JavaScript library для ThemeParks.Wiki API. В README он представлен как typed TypeScript/JavaScript SDK для ThemeParks.wiki API.  

ThemeParks_Python

Python SDK for API consumers

Описан как Python API Library для ThemeParks.Wiki. README называет его typed Python SDK для ThemeParks.wiki API.  

apigenerator

API client generation tooling

Описан как инструмент, который generates OpenAPI clients to interact with ThemeParks.wiki. В README отдельно упоминается генерация обновлённых клиентов и публикация JavaScript/Python SDK.  

pebble

consumer app / example client

Описан как Pebble app for ThemeParks.wiki. Поэтому я не отношу его к ядру системы, но держу рядом как возможный пример потребителя публичного API.  

PlayStoreWatch

supporting utility

Описан как Basic Play Store app version watcher. По названию и описанию это похоже на вспомогательную утилиту, а не на центральный слой движения theme park data.  

android-frida

debugging / reverse-engineering helper scripts

Описан как Frida helper scripts for debugging Android. На первом проходе я отношу его к вспомогательным debugging-инструментам, а не к основному продуктовому контуру.  

5. Dependency matrix: карта проверенных связей

Я конечно не буду предлагать строить карту из предыдущей таблицы. Потому что связи не очевидны. Тут немного сыграем в Морской бой. Сперва покажу результат, а потом скажу, как таблицу заполнить.

From / To

parksapi

typelib

ThemeParks.wiki API

ThemeParks_JavaScript

ThemeParks_Python

apigenerator

pebble

PlayStoreWatch

android-frida

parksapi

—

depends on

powers

—

—

—

—

—

—

typelib

—

—

types for API

—

—

—

—

—

—

ThemeParks.wiki API

—

—

—

consumed by

consumed by

has OpenAPI spec

consumed by

—

—

ThemeParks_JavaScript

—

—

calls API

—

—

—

—

—

—

ThemeParks_Python

—

—

calls API

—

—

—

—

—

—

apigenerator

—

—

uses OpenAPI spec

generates clients

generates clients

—

—

—

—

pebble

—

—

calls API

—

—

—

—

—

—

PlayStoreWatch

—

—

—

—

—

—

—

—

—

android-frida

—

—

—

—

—

—

—

—

—

Очевидно, пишем названия репозиториев в строчку и в столбик.

Как найти связи?

  • Прежде всего конечно в манифест файлах - package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, pom.xml, build.gradle

  • Выполнить grep'ом поиск по репозиторию по ключевым словам пакетов

  • Проверить CI/CD файлы, там тоже часто много подсказок

Тут 8 репозиториев, не стесняйтесь использовать ИИ и автоматизацию в случае если их 80. Да и с 8 тоже не помешает.

На примере узла ThemeParks.wiki API этот путь будет такой:

  • в package.json засветился "@themeparks/typelib": "^1.1.5"

  • в ThemeParks_JavaScript/package.json репозиторий описан как Official SDK for the ThemeParks.wiki API => ThemeParks_JavaScript — подтверждённый SDK для публичного API

  • В ThemeParks_Python/pyproject.toml описание такое же - Official SDK for the ThemeParks.wiki API => ThemeParks_Python тоже подтверждённый SDK для публичного API

  • README у ThemeParks_JavaScript и ThemeParks_Python подтверждают связи

  • В pebble/README нашли, что Pebble - smartwatch app для ThemeParks.wiki. В architecture notes сказано, что PKJS на стороне телефона вызывает ThemeParks.wiki HTTP API и передаёт данные на часы. => pebble — подтверждённый consumer API

  • Проверили codegen / tooling: В apigenerator/README написано, что он генерирует OpenAPI clients для ThemeParks.wiki. В generate_config.js видно, что генератор использует файл ../themeparksapi/docs/v1.yaml => apigenerator связан с ThemeParks.wiki API через OpenAPI contract

Итого 6 связей нашли для этого репо:


parksapi -> typelib
parksapi -> ThemeParks.wiki API
ThemeParks.wiki API -> ThemeParks_JavaScript
ThemeParks.wiki API -> ThemeParks_Python
ThemeParks.wiki API -> pebble
apigenerator -> ThemeParks.wiki API / OpenAPI contract

Да, довольно запарно, но я уверена вы справитесь с автоматизацией, чтобы получить данный полезный артефакт.

6. Рабочая карта

Когда у нас на руках все связи, мы готовы сделать из этого карту. Опять же, не пренебрегайте автоматизацией, если ей владеете. Из 80 репо сделать карту вручную не так уж просто.

Отдельно поясню, почему на схеме parksapi и ThemeParks.wiki API показаны разными блоками.

Это не два репозитория с одинаковой ролью. Это два разных уровня карты.

parksapi — это репозиторий, где находится backend library для получения и подготовки live theme park data. А ThemeParks.wiki API — это публичная API-граница, через которую эти данные уже доступны внешним потребителям. В README parksapi прямо сказано, что библиотека powers the free API at ThemeParks.wiki, а клиентские библиотеки нужны, чтобы получать данные из ThemeParks.wiki API, а не запускать parksapi напрямую.  

parksapi — это место, где, судя по публичному описанию, живёт логика получения и подготовки данных.

ThemeParks.wiki API — это публичная поверхность, через которую эти данные потребляют SDK и внешние клиенты.

Для онбординга это полезное разделение.

Репозиторий отвечает на вопрос: где живёт логика сбора и подготовки данных?
 API boundary отвечает на другой вопрос: через какую публичную поверхность эти данные потребляют SDK и внешние клиенты?

Поэтому рабочая карта делится на две части.

Первая часть — основной продуктовый контур:

  • parksapi — вероятное ядро сбора и подготовки данных;

  • typelib — общий язык типов и схем;

  • ThemeParks.wiki API — публичная граница, через которую данные уходят наружу;

  • ThemeParks_JavaScript и ThemeParks_Python — SDK для потребителей API;

  • apigenerator — tooling, который помогает генерировать или обновлять API-клиенты.

Вторая часть — вспомогательные и периферийные репозитории:

  • pebble — отдельное клиентское приложение, возможный потребитель публичного API;

  • PlayStoreWatch — вспомогательная утилита;

  • android-frida — debugging/helper scripts для Android.

Так плоский список репозиториев превращается в первую рабочую карту системы. Она ещё не объясняет всё, но уже показывает главное: где вероятное ядро, где публичная граница, где потребители, а где инструменты вокруг основного контура.

7. Итоговые onboarding artifacts дня

  • Таблица репозиториев

  • dependency matrix

  • relationship diagram

Relationship diagram - главный артефакт этапа. Его можно дать новичку в первый день, чтобы он не собирал эту карту заново в голове.

Этого уже достаточно, чтобы перейти от вопроса:

  • какие репозитории есть и как они связаны?

к следующему:

  • какие данные между ними движутся?

8. Дальше — data flow

Теперь у нас есть первый рабочий слой карты:

  • какие репозитории есть

  • какую роль они играют

  • как связаны между собой

Это уже сильно лучше, чем просто список доступов и README.

Но пока мы ответили только на вопрос:

  • кто есть кто?

Следующий вопрос глубже:

  • что между ними движется?

В следующей статье я наложу на эту карту data flow:

  • откуда данные приходят

  • где превращаются во внутреннюю модель

  • где нормализуются

  • куда уходят

  • кто их потребляет

На примере ThemeParks это значит: посмотреть, как данные о парках проходят путь от внешних источников к parksapi, становятся подготовленными live data, выходят через публичный API и становятся удобными для SDK.

До новых встреч и спасибо за прочтение!