Overview
Add comprehensive markdown documentation to explain how the data governance and sync-system work in CrystaLearn.
Documentation Scope
Create a set of documents in /docs/architecture/ (or /docs/architecture/sync/ if a more organized structure makes sense) covering:
- High-level architecture of syncing entities with external source providers (e.g., Azure Board, GitHub, LinkedIn, Twitter)
- Explanation that CrystaLearn aims not to be the source of truth for various data contexts, but acts as a consumer and normalized aggregator of external data
Example Entities & Services
For example, for tasks synced from Azure Board:
CrystaTask: our standard model representing a taskCrystaTaskService: business logic and UI access for CrystaTask, read-only (no direct add/delete/update)CrystaTaskAzureBoardSyncService: responsible for syncing CrystaTasks to/from Azure BoardAzureBoardService: low-level service for interacting with the external resource (makes API calls to Azure Board)
Repeat this pattern for documents (synced by GitHub) and social activities (synced by LinkedIn, Twitter, etc):
- Models: CrystaTask, CrystaDocument, CrystaSocialActivity
- Services: [Entity]Service, [Entity][Provider]SyncService, [Provider]Service
File Structure Suggestion
/docs/architecture/sync-overview.md (overall system and sync architecture with mermaid)/docs/architecture/sync-task-overview.md (task sync details)/docs/architecture/sync-document-overview.md (document sync details)/docs/architecture/sync-social-activity-overview.md (social activity sync details)
Each document should use diagrams (like mermaid) where helpful and clearly highlight how syncing works, what services are involved, and the direction of data flow.
Deliverables
- Draft and commit the documentation markdown files to
/docs/architecture/ or /docs/architecture/sync/ as appropriate
- Only documentation is required, not the code
Overview
Add comprehensive markdown documentation to explain how the data governance and sync-system work in CrystaLearn.
Documentation Scope
Create a set of documents in
/docs/architecture/(or/docs/architecture/sync/if a more organized structure makes sense) covering:Example Entities & Services
For example, for tasks synced from Azure Board:
CrystaTask: our standard model representing a taskCrystaTaskService: business logic and UI access for CrystaTask, read-only (no direct add/delete/update)CrystaTaskAzureBoardSyncService: responsible for syncing CrystaTasks to/from Azure BoardAzureBoardService: low-level service for interacting with the external resource (makes API calls to Azure Board)Repeat this pattern for documents (synced by GitHub) and social activities (synced by LinkedIn, Twitter, etc):
File Structure Suggestion
/docs/architecture/sync-overview.md(overall system and sync architecture with mermaid)/docs/architecture/sync-task-overview.md(task sync details)/docs/architecture/sync-document-overview.md(document sync details)/docs/architecture/sync-social-activity-overview.md(social activity sync details)Each document should use diagrams (like mermaid) where helpful and clearly highlight how syncing works, what services are involved, and the direction of data flow.
Deliverables
/docs/architecture/or/docs/architecture/sync/as appropriate