C4 Architecture Micro-Learning White-Label App Factory (Flutter + Django) Сгенерировано на основе: PRD, OpenAPI Data Contract, Factory Idea, Implementation Plan, DoD

Формат: C4 Model — Level 1 (Context), Level 2 (Containers), Level 3 (Components), Level 4 (Code/Modules). Цель: максимально детально описать, как устроена архитектура фабрики приложений, зачем каждый компонент, из чего состоит и как взаимодействует с другими.

1. Свод требований и ограничений (из документов)

Ключевая бизнес-цель: выпускать множество тематических приложений («Пушкин», «Шагал», «Понимать кино») из одной кодовой базы, с минимальной ручной работой. Контент и поведение должны управляться из админки. Сборка и публикация — полностью автоматические.

1.1 Нефункциональные цели (KPI)

• Retention: D1/D7/D30 (из PRD).
• Quiz engagement + accuracy (из PRD).
• Стабильность: crash-free sessions, API error rate, build failure rate (из PRD).
• Cost: стоимость поддержки N приложений (build time / release time) (из PRD).

1.2 Обязательные функции платформы

• White-label: один Flutter core → много приложений с разными bundle ID / applicationId, иконками и темами.
• Offline-first: предзагрузка контента, кеш медиа, устойчивость в airplane mode.
• Мультимедиа: текст/изображение/аудио/видео (по PRD).
• Подписки/IAP: монетизация + server-side валидация.
• Квиз-повторение (swipe): вопросы по пройденному после нескольких дней, с игровой механикой.
• Автосборка из админки: build одного бренда и rebuild всех брендов.
• Автопубликация: загрузка билдов в App Store / Google Play без ручной операции.
• Аналитика и A/B: события, когорты, remote config/feature flags.

1.3 Definition of Done (контроль качества)

DoD из файла фиксирует обязательность: тестов (unit/widget/integration), статических проверок, логирования, crash reporting, предпросмотров BrandConfig/Content, безопасных процедур publish/bulk ops, документации API и пайплайнов.

2. C4 Level 1 — System Context

Система: Micro-Learning App Factory — платформа, которая производит и обслуживает множество образовательных приложений.

2.1 Акторы (люди)

Актор	Что делает	Почему важно
Learner (пользователь)	Проходит уроки 60 секунд/день, получает уведомления, проходит swipe-квизы, покупает подписку.	Основной источник DAU/retention/дохода.
Editor/Methodist	Создаёт уроки, переводы, вопросы для повторения, публикует версии контента.	Контент — главный moat и рычаг роста.
Release/DevOps	Управляет ключами, публикациями в сторах, откатами, стабильностью CI.	Без автоматизации и релиз-надёжности фабрика не масштабируется.
Marketer/Growth	Меняет paywall/офферы/эксперименты, следит за конверсией и когорточками.	Монетизация и рост.
Support	Разбирает проблемы подписок, доступов, refunds, GDPR-экспорт/удаление.	Снижение churn и рисков.

2.2 Внешние системы

Система	Роль
Apple App Store Connect	Приём и публикация iOS билдов (TestFlight/Production).
Google Play Console	Приём и публикация Android билдов (Internal/Alpha/Production).
APNs/FCM	Пуш-уведомления (желательно FCM унифицировано).
Analytics Provider (Firebase/Amplitude/Mixpanel)	Сбор событий, retention, воронки.
Crash reporting (Crashlytics/Sentry)	Краши/ошибки для стабильности KPI.
Object Storage (S3/GCS)	Хранение медиа и артефактов билдов/логов.
CDN (CloudFront/Cloudflare)	Доставка медиа и ускорение.
Payment validation endpoints (Apple/Google/RevenueCat)	Проверка подписок/квитанций.

2.3 Context диаграмма

graph TB
    subgraph Actors
        learner["👤 Learner<br/>Daily micro-lessons, quizzes, subscription"]
        editor["👤 Editor/Methodist<br/>Lessons, translations, quiz questions"]
        release["👤 Release/DevOps<br/>Keys, CI/CD, store releases"]
        marketer["👤 Marketer/Growth<br/>Paywall, experiments, conversion"]
        support["👤 Support<br/>Entitlements, refunds, GDPR"]
    end

    factory["🏭 Micro-Learning App Factory<br/>White-label: content, build, deploy, analytics"]

    subgraph External["External Systems"]
        appstore["Apple App Store Connect"]
        play["Google Play Console"]
        fcm["FCM / APNs"]
        analytics["Analytics Provider"]
        crash["Crash Reporting"]
        storage["Object Storage S3/GCS"]
        cdn["CDN"]
        receipts["Receipt Validation"]
    end

    learner -->|"Mobile app"| factory
    editor -->|"Admin UI"| factory
    release -->|"Build center"| factory
    marketer -->|"Paywall config"| factory
    support -->|"Admin UI"| factory

    factory -->|"Fastlane"| appstore
    factory -->|"Fastlane"| play
    factory -->|"HTTP API"| fcm
    factory -->|"SDK/HTTP"| analytics
    factory -->|"SDK"| crash
    factory -->|"S3/GCS"| storage
    factory -->|"HTTPS"| cdn
    factory -->|"HTTPS"| receipts

3. C4 Level 2 — Container Diagram

Контейнеры — крупные исполняемые части системы (приложения/сервисы/хранилища).

3.1 Контейнеры и их назначение

Container	Технологии	Зачем существует	Главные интерфейсы
Flutter Mobile Apps (N брендов)	Flutter; flavors; offline DB; media cache	Runtime для пользователя: уроки, офлайн, квизы, paywall, события	HTTPS API + FCM + Store IAP
Django Control Plane (Web)	Django + custom admin UI	Управление брендами, контентом, квизами, билдами, релизами	Admin Web + Admin API
Public API (DRF)	Django REST Framework	Версионированное API для клиентов	/api/v1/*
Build Orchestrator	Celery + Redis	Создаёт/ведёт BuildJobs, триггерит CI, принимает callbacks	workflow triggers + callbacks
CI/CD System	GitHub Actions/GitLab CI + Fastlane	Сборка матрицей (brand x platform), подпись, публикация в сторах	Fastlane supply/pilot/deliver
PostgreSQL	PostgreSQL	Источник правды: бренды, контент, прогресс, квизы, билды	SQL
Redis	Redis	Брокер/кеш для Celery, rate limits, locks	Redis
Object Storage	S3/GCS	Медиа, артефакты билдов, логи CI	HTTPS
CDN	CloudFront/Cloudflare	Доставка медиа пользователям быстро	HTTPS
Analytics Stack	Firebase/Amplitude + (опц.) BigQuery	События, retention, воронки, эксперименты	SDK/Exports

3.2 Container диаграмма

graph TB
    subgraph Factory["Micro-Learning App Factory"]
        mobile["📱 Flutter Mobile Apps<br/>N brands, offline, quizzes"]
        web["🖥️ Control Plane<br/>Django Admin UI"]
        api["🔌 Public API<br/>Django REST Framework"]
        orchestrator["⚙️ Build Orchestrator<br/>Celery + Redis"]
        db[("🗄️ PostgreSQL<br/>Content, progress, quizzes")]
        cache[("Redis<br/>Broker, cache, locks")]
        storage["📦 Object Storage<br/>S3/GCS"]
        cdn["🌐 CDN<br/>Media delivery"]
        analytics["📊 Analytics<br/>Firebase/Amplitude"]
    end

    subgraph Ext["External"]
        ci["CI/CD<br/>GitHub Actions + Fastlane"]
        appstore["App Store Connect"]
        play["Google Play Console"]
        fcm["FCM / APNs"]
        receipts["Receipt Validation"]
    end

    mobile -->|"HTTPS/JSON"| api
    web -->|"SQL"| db
    api -->|"SQL"| db
    orchestrator -->|"Redis"| cache
    orchestrator -->|"SQL"| db
    orchestrator -->|"workflow dispatch"| ci
    ci -->|"HTTPS"| storage
    ci -->|"Fastlane"| appstore
    ci -->|"Fastlane"| play
    api -->|"HTTPS"| storage
    storage -->|"Origin"| cdn
    mobile -->|"HTTPS"| cdn
    mobile -->|"SDK"| analytics
    api -->|"HTTP"| fcm
    api -->|"HTTPS"| receipts

4. C4 Level 3 — Components

Уровень компонентов показывает внутреннюю структуру ключевых контейнеров. Ниже — самое детальное описание: зачем каждый компонент, данные, интерфейсы, и точки расширения.

4.1 Components: Django Control Plane + Public API

4.1.1 Brands & Configuration

• Brand Registry: сущность Brand (bundle ids, app ids, статус, владельцы).
• BrandConfig Snapshots: неизменяемые снимки конфигурации для воспроизводимых билдов.
• Theme/Assets Manager: загрузка и валидация иконок, splash, шрифтов; генерация наборов.
• Feature Flags Manager: флаги и параметры (включая paywall placements, quiz rules).
• Preview/Simulator: предпросмотр BrandConfig и контентного флоу (из DoD).

4.1.2 Content Studio

• Track Editor: правила day unlock (rollover time, catch-up, archive rules).
• Lesson Editor (block-based): Hook/Insight/Expansion/Reflection как блоки; длительность; теги.
• Asset Pipeline: привязка медиа, проверки размеров/кодеков, генерация adaptive streams (опц.).
• Localization Manager: переводы уроков/вопросов; проверка completeness по языкам.
• Content Versioning: публикация версий контента (draft -> published) и выдача дельта-обновлений клиентам.

4.1.3 Quiz Studio

• Question Bank: хранение утверждений True/False + explanation + ссылки на уроки/теги.
• Schedule Rules: после N дней / по spaced repetition; frequency caps (max 1 quiz/day из PRD).
• Selection Engine: выбирает вопросы по темам со слабой точностью и давностью; исключает недавние.
• Scoring Rules: баллы/комбо/награды; premium расширения (например, «архив ошибок»).

4.1.4 Entitlements & Receipts

• Product Catalog: продукты подписок/IAP по бренду и региону.
• Receipt Verification: server-side проверка Apple/Google (не доверять клиенту).
• Entitlement Engine: расчёт прав доступа (premium, архив, офлайн-пакеты) + кеширование.
• Refund/Support Tools: ручное изменение entitlements, обработка обращений.

4.1.5 Build Center & Orchestrator

• BuildJob Service: single build / batch build / rebuild all; статусы и SLA.
• CI Trigger Adapter: workflow_dispatch/trigger, параметры матрицы (brand x platform).
• Callback Receiver: прием статусов из CI (build started/succeeded/failed, store upload).
• Artifact Registry: ссылки на AAB/IPA, логи, changelog snapshot.
• Safety Gates: подтверждение “опасных” операций (bulk publish) из DoD.

4.1.6 Observability & Audit

• Audit Log: кто и что поменял (BrandConfig, контент, цены, публикации).
• Rate limiting / Abuse protection: ограничение login/sync.
• Health endpoints + Sentry integration: алерты по 5xx и Celery backlog.

4.2 Components: Flutter Mobile Runtime

4.2.1 Bootstrap & Configuration

• BrandConfig Bootstrapper: загрузка /brand/config, локальный кеш, fallback.
• Remote Config Adapter: получение параметров и A/B вариаций.
• Feature Flag Resolver: единая точка, откуда UI/логика читают флаги.

4.2.2 Offline-first Data Layer

• Local DB (Drift): lessons, blocks, assets index, progress, quiz history, pending events.
• KV Store (SharedPreferences): настройки, токены, onboarding flag, последний config hash.
• Media Cache Manager: загрузка ассетов в файл-систему, контроль checksum/ttl.
• Prefetch Scheduler: prefetch N дней, правила wifi-only для видео.

4.2.3 Daily Flow Engine

• Day Unlock Calculator: вычисляет “какой день” (timezone aware) и какой урок доступен.
• Today Screen State Machine: состояния (loading, offline, no-content, ready, error).
• Completion Handler: отмечает завершение, обновляет streak, ставит sync task.

4.2.4 Swipe Quiz Engine

• Quiz Trigger: запуск по правилам (после N дней / scheduled).
• Question Selection (client-side fallback): если офлайн — выбрать из локального question bank по правилам.
• Swipe UI: жесты вправо/влево; анимации; accessibility.
• Instant Feedback: показываем correct/incorrect + explanation + CTA “повторить урок”.
• Scoring & Rewards: очки, комбо, бейджи; запись в историю.

4.2.5 Payments & Entitlements

• Paywall Renderer: layout driven by config (не хардкодить тексты/цены).
• IAP Client: in_app_purchase / RevenueCat SDK.
• Receipt Uploader: отправка receipts на сервер для валидации.
• Entitlement Cache: локальный кеш прав доступа для оффлайна.

4.2.6 Sync & Analytics

• Sync Queue: пачки событий и прогресса; idempotency keys; ретраи.
• Delta Puller: /content/updates?since=...; применяет миграции локальных данных.
• Analytics Emitter: события из PRD (lesson_view/complete, quiz_started/completed, paywall_view, purchase_success).
• Crash Reporting: Crashlytics/Sentry; связь с brand/version.

4.2.7 Notifications

• FCM Receiver: push от сервера (например, контент обновился/важный анонс).
• Local Notification Scheduler: ежедневный пинг; frequency caps; quiet hours.

5. C4 Level 4 — Code (Modules/Packages)

Уровень кода — практическая структура репозиториев и модулей. Это нужно, чтобы команда могла параллельно работать и чтобы фабрика приложений не превратилась в монолит.

5.1 Репозитории

Repo	Содержимое	Зачем
mobile/	Flutter monorepo: app_core + feature packages + brand wrappers	Единый код для всех брендов.
backend/	Django: control plane + APIs + celery workers	Единая точка управления.
infra/	CI templates, Fastlane, scripts, IaC (Terraform)	Воспроизводимая инфраструктура и релизы.
content/ (optional)	Контент как код: источники, медиа манифесты, переводы	Версионирование и review контента.

5.2 Flutter packages (целевая структура)

Примечание: Ниже — целевая архитектура для всех 9 эпиков. Реализованные модули — см. секцию 5.4.2.

Package	Ответственность	Примечание
app_core	DI, routing, theming, error handling, base widgets	Не зависит от конкретного бренда.
feature_content	Lesson rendering, blocks, media player integration	Server-driven blocks.
feature_quiz	Swipe UI, selection, scoring, history	Изолировать от остального.
feature_payments	Paywall + IAP + entitlement cache	Сильная изоляция и тесты.
data_layer	Repositories, remote/local sources, sync queue	Общий слой данных.
analytics	Event schema + providers	Одинаково для всех брендов.
brand_app_	Тонкий wrapper, main entry, assets hooks	Минимум кода.

5.3 Django apps (целевая структура)

Примечание: Ниже — целевая архитектура для всех 9 эпиков. Реализованные apps — см. секцию 5.4.1.

Django app	Ответственность
brands	Brand, BrandConfig snapshots, themes/assets, flags
content	Tracks, lessons, blocks, assets, localization
quizzes	Rules, question bank, selection, results
builds	BuildJobs, targets, callbacks, artifact registry
payments	Receipts, entitlements, products, support tools
analytics	Aggregates, exports, cohort endpoints (опц.)
audit	Audit log, permissions, RBAC

5.4 Реализованные модули (текущее состояние)

5.4.1 Backend Django apps (реализовано)

Django app	Статус	Что реализовано
apps/auth	Done	DeviceSession, anonymous JWT, refresh с ротацией
apps/content	Done	Course, AppVariant, ContentItem, MediaAsset, ContentTranslation, DeletedContentItem; сервисы: locale resolution, day access check, manifest (since_version + deleted_item_ids + content_item_id); auto content_hash (SHA-256 on publish), content_version bump (F+1 on publish); lifecycle state machine (draft→scheduled→published→archived), transition API, Celery scheduled publishing (beat: every 15min, autoretry 3x, backoff 60s)
apps/progress	Done	UserProgress, DayCompletion; timezone-aware streak (client_timezone via zoneinfo), idempotent complete_day
apps/bootstrap	Done	Aggregator: config + course + progress + today_item
apps/quiz	Done	QuizQuestion, QuizSession, QuizAnswer; selection with cooldown, scoring, idempotent answer/complete, review tags

Middleware и core: - CorrelationIDMiddleware (X-Correlation-ID → structlog contextvars) - ErrorEnvelope ({error: {code, message, details, request_id}}) - drf-spectacular (OpenAPI auto-gen: Swagger UI, ReDoc)

Admin: - Django Unfold 0.78.1 — Material UI admin theme (sidebar navigation, Material icons) - Content Admin: CourseAdmin, AppVariantAdmin (fieldsets), ContentItemAdmin (inlines + lifecycle actions) - Quiz Admin: QuizQuestionAdmin, QuizSessionAdmin, QuizAnswerAdmin - Auth Admin: DeviceSessionAdmin

Тесты: 320 (pytest, SQLite in-memory), покрытие ~97%

5.4.2 Flutter packages (реализовано)

Структура frontend/lib/:

Package	Статус	Что реализовано
app/	Done	App root, GoRouter (splash→today→completion), Material 3 theme (light/dark)
core/	Done	ApiConstants, AppException, NetworkException
data/local/	Done	TokenStorage (SharedPreferences); Drift SQLite DB (ContentItems, ContentTranslations, MediaAssets, ProgressEntries, SyncMetadataEntries); 3 DAOs (ContentDao, ProgressDao, SyncMetadataDao); AppDatabase singleton via Riverpod
data/remote/	Done	ApiClient (Dio + AuthInterceptor + ErrorInterceptor + LoggingInterceptor), AuthService, BootstrapService
data/remote/models/	Done	26 Freezed DTO: AuthResponse, BootstrapResponse, ContentItem, ProgressState, AppVariantConfig, ContentManifest, ManifestItem, ManifestAsset + 14 nested
data/sync/	Done	SyncService (manifest pull, diff computation, apply), SyncResult, SyncDiff; uses SyncMetadata for content_version tracking
data/repositories/	Done	AuthRepository, BootstrapRepository, ContentRepository (cache-first: DB→API→cache, cacheContentItem public for sync), ProgressRepository (local-first: write DB + API best-effort + dirty flag)
features/bootstrap/	Done	SplashScreen (auth→bootstrap→navigate, onboarding redirect), bootstrapProvider
features/daily/	Done	TodayScreen (settings icon), CompletionScreen, ContentBlockRenderer (body_rich JSON), StreakIndicator, TodayState notifier
features/onboarding/	Done	OnboardingScreen (3-page PageView: Welcome→Language→Ready), OnboardingNotifier (SharedPreferences persistence), LanguageSelector (EN/RU with flags)
features/settings/	Done	SettingsScreen (language, sync status, about), SettingsNotifier (SharedPreferences), reuses LanguageSelector
features/sync/	Done	SyncNotifier (idle→syncing→success/error), debounces concurrent calls, exposes SyncState
l10n/	Done	gen-l10n (en/ru), plural forms for streakDays, 10 onboarding + 9 settings keys

State management: Riverpod 2.6 + riverpod_generator (@riverpod code-gen)

Тесты: 170 (flutter test), dart analyze 0 issues

6. API Contract (выжимка по OpenAPI Data Contract)

Ниже — как API группируется и зачем. Полная спецификация хранится в OpenApiDataContract.yaml.

6.1 Основные группы endpoint-ов

• Auth: login/refresh (JWT).
• Brand bootstrap: получение BrandConfig + flags.
• Content: список треков, урок дня, дельта обновлений.
• Progress: отметить завершение урока, обновить streak.
• Quiz: следующая викторина, ответы, результаты.
• Payments: verify receipts, entitlements.
• Events: batch events (если не только Firebase). Принцип: все write-операции (POST) должны быть идемпотентными (idempotency_key) — это критично для офлайна и ретраев.

7. Build/Deploy — детальный жизненный цикл (пошагово)

7.1 Сборка одного бренда из админки

1. Editor/Release выбирает Brand и нажимает BUILD (platforms: iOS/Android; track: internal/beta/prod).
2. Control Plane сохраняет BrandConfigSnapshot (immutable) и создаёт BuildJob + BuildTargets (brand x platform).
3. Celery task отправляет trigger в CI (workflow_dispatch) с job_id и brand_code.
4. CI забирает snapshot по admin API, генерирует assets/конфиги, применяет flavor/scheme.
5. CI собирает артефакт (AAB/IPA), прогоняет smoke checks (например, анализатор/минимальные тесты).
6. Fastlane подписывает и грузит: Play (supply) и App Store (pilot/deliver).
7. CI пушит callback в Control Plane: build succeeded + store upload status + artifact/logs URLs.
8. Control Plane обновляет BrandVersion (release record) и показывает статус в Build Center.

7.2 Массовая пересборка всех брендов (core change)

1. Merge в main ветку mobile core (или ручная команда REBUILD ALL).
2. Control Plane создаёт batch BuildJob со списком всех активных брендов.
3. CI запускает matrix builds (brand x platform) с ограничением параллелизма (особенно iOS).
4. При ошибках: retries по политике; критические фейлы — stop-the-line + алерт.
5. После успешного прогона: автообновление в сторах по выбранному track или через staged rollout.

7.3 Rollback стратегия

• App binary rollback: выпуск новой версии с fix/rollback (обычно быстрее и безопаснее, чем «откаты» в сторах).
• Server-side rollback: фичефлаги/remote config выключают проблемную функцию без релиза.
• Content rollback: публикация предыдущей версии content pack (server-side).

8. Качество, тестирование и приемка (по DoD)

8.1 Backend (Django)

• Unit tests: правила day unlock, quiz selection, receipts verification, сериализаторы.
• API contract tests: OpenAPI schema проверяется в CI.
• Migration safety: миграции и обратная совместимость для клиентов.
• Security tests: RBAC, audit trail, rate limiting.

8.2 Mobile (Flutter)

• Widget tests: Today screen states, quiz swipe gestures, paywall states.
• Integration tests: offline -> online sync; receipt verify flow; prefetch.
• Static checks: dart format, analyzer, lints.
• Crash reporting: включено и проверено (brand/version).

8.3 CI/CD

• Pipeline reproducibility: build from snapshot, deterministic assets.
• Store upload verification: подтверждение артефакта и статуса в сторах.
• Safety: bulk publish требует подтверждения/ролей, логируется (DoD).

9. Почему так (Design Rationale)

• White-label через конфиги и flavor-идентичность: минимизирует стоимость запуска новых приложений.
• Control Plane как источник правды: обеспечивает операционную управляемость и воспроизводимость билдов.
• Immutable snapshots: гарантируют, что билд можно повторить и расследовать инциденты.
• Offline-first + idempotency: ключ к реальному мобильному опыту и отсутствию потерь прогресса.
• Swipe-quizzes: системная механика удержания, плюс данные для адаптации контента.
• Автодеплой: единственный способ обслуживать десятки/сотни приложений без «релиз-ада».

10. Приложение: чек-лист внедрения (коротко)

1. Сначала — скелет: BrandConfig bootstrap, Today flow, локальная БД, sync queue.
2. Затем — Content Studio + публикация версий контента + delta updates.
3. Затем — Quiz Studio + swipe engine + расписание повторений.
4. Затем — Build Center + CI triggers + Fastlane upload (internal testing).
5. Затем — receipts/entitlements + paywall AB + observability.
6. После — масштабирование числа брендов и оптимизация стоимости CI/видео.