# maverickbms/codeguard-pro architecture

> Architecture diagram of the GitHub repository maverickbms/codeguard-pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maverickbms/codeguard-pro
- Repository: https://github.com/maverickbms/codeguard-pro

## Overview

CodeGuard Pro is a local-first learning platform: the learner opens the Electron desktop app, which starts a loopback Django server and presents its UI; learners use it to study the ASCENSO roadmap and record progress. Django also provides assessment, tutoring, challenges, and gamification, backed by local SQLite data. A separate knowledge workflow edits and publishes versioned content, then can pull signed updates. The README documents these capabilities; sampled excerpts confirm selected service calls, but not the full view-to-service wiring.

Main entry points: [`electron/main.js`](https://github.com/maverickbms/codeguard-pro/blob/main/electron/main.js) (Electron shell), [`apps/roadmaps/services.py`](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services.py) (Roadmap services), [`apps/roadmaps/views.py`](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/views.py) (Roadmap views), [`apps/roadmaps/services_evaluacion.py`](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services_evaluacion.py) (Assessment engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop runtime"]
  node_electron["Electron shell<br/>[main.js]"]
  node_django["Local Django server<br/>[server_entry.py]"]
end

subgraph group_learning["Learning experience"]
  node_ui["Learning interface<br/>[codeguard.js]"]
  node_roadmap_views["Roadmap views<br/>[views.py]"]
  node_roadmap_logic["Roadmap services<br/>[services.py]"]
  node_academic_data[("Roadmap and progress<br/>[models.py]")]
  node_assessment["Assessment engine"]
  node_assessment_data[("Evaluation records")]
  node_tutoring["Local tutor<br/>[services.py]"]
  node_tutoring_data[("Tutoring sessions<br/>[models.py]")]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_content_editorial["Editorial workflow<br/>[publisher.py]"]
  node_content_import["Content import<br/>[content_import.py]"]
  node_package_distribution["Signed packages<br/>[distribution.py]"]
  node_package_installer["Package installer<br/>[installer.py]"]
  node_sync_client["Knowledge sync<br/>[sync_client.py]"]
end

subgraph group_engagement["Practice and rewards"]
  node_challenges["Challenges<br/>[services.py]"]
  node_gamification["Gamification<br/>[services.py]"]
end

subgraph group_platform["Identity and local data"]
  node_accounts["Identity services<br/>[services.py]"]
  node_audit["Audit logging<br/>[services.py]"]
  node_local_data[("Local application data<br/>[base.py]")]
  node_backup["Backup tools<br/>[backup.py]"]
end

node_learner(("Learner"))
node_ollama["Ollama local"]

node_learner -->|"opens app"| node_electron
node_electron -->|"starts server"| node_django
node_electron -->|"checks health"| node_django
node_electron -->|"starts sync"| node_sync_client
node_learner -->|"studies locally"| node_ui
node_ui -.->|"uses roadmap"| node_roadmap_views
node_roadmap_views -.->|"delegates to"| node_roadmap_logic
node_roadmap_logic -->|"records progress"| node_academic_data
node_roadmap_views -.->|"submits answers"| node_assessment
node_assessment -->|"stores results"| node_assessment_data
node_assessment -->|"checks criteria"| node_roadmap_logic
node_learner -->|"requests hints"| node_tutoring
node_tutoring -->|"requests explanation"| node_ollama
node_tutoring -->|"stores sessions"| node_tutoring_data
node_content_import -.->|"imports drafts"| node_content_editorial
node_content_editorial -.->|"publishes package"| node_package_distribution
node_sync_client -->|"verifies package"| node_package_distribution
node_sync_client -->|"installs updates"| node_package_installer
node_package_installer -->|"updates catalog"| node_academic_data
node_learner -->|"records result"| node_challenges
node_challenges -->|"persists attempt"| node_local_data
node_roadmap_logic -.->|"awards progress"| node_gamification
node_gamification -->|"reads completion"| node_academic_data
node_learner -->|"authenticates optionally"| node_accounts
node_accounts -->|"records access events"| node_audit
node_audit -->|"stores events"| node_local_data
node_learner -->|"runs backup command"| node_backup
node_backup -->|"backs up database"| node_local_data

click node_electron "https://github.com/maverickbms/codeguard-pro/blob/main/electron/main.js"
click node_django "https://github.com/maverickbms/codeguard-pro/blob/main/server_entry.py"
click node_ui "https://github.com/maverickbms/codeguard-pro/blob/main/static/js/codeguard.js"
click node_roadmap_views "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/views.py"
click node_roadmap_logic "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services.py"
click node_academic_data "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/models.py"
click node_assessment "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services_evaluacion.py"
click node_assessment_data "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/models_evaluacion.py"
click node_tutoring "https://github.com/maverickbms/codeguard-pro/blob/main/apps/tutoring/services.py"
click node_tutoring_data "https://github.com/maverickbms/codeguard-pro/blob/main/apps/tutoring/models.py"
click node_content_editorial "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/publisher.py"
click node_content_import "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/content_import.py"
click node_package_distribution "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/distribution.py"
click node_package_installer "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/installer.py"
click node_sync_client "https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/sync_client.py"
click node_challenges "https://github.com/maverickbms/codeguard-pro/blob/main/apps/challenges/services.py"
click node_gamification "https://github.com/maverickbms/codeguard-pro/blob/main/apps/gamification/services.py"
click node_accounts "https://github.com/maverickbms/codeguard-pro/blob/main/apps/accounts/services.py"
click node_audit "https://github.com/maverickbms/codeguard-pro/blob/main/apps/audit/services.py"
click node_local_data "https://github.com/maverickbms/codeguard-pro/blob/main/config/settings/base.py"
click node_backup "https://github.com/maverickbms/codeguard-pro/blob/main/apps/core/backup.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_electron,node_django toneBlue
class node_ui,node_roadmap_views,node_roadmap_logic,node_academic_data,node_assessment,node_assessment_data,node_tutoring,node_tutoring_data toneAmber
class node_content_editorial,node_content_import,node_package_distribution,node_package_installer,node_sync_client toneMint
class node_challenges,node_gamification toneRose
class node_accounts,node_audit,node_local_data,node_backup,node_learner,node_ollama toneIndigo
```

## Components

### Desktop runtime

- [Electron shell](https://github.com/maverickbms/codeguard-pro/blob/main/electron/main.js): `electron/main.js`
- [Local Django server](https://github.com/maverickbms/codeguard-pro/blob/main/server_entry.py): `server_entry.py`

### Learning experience

- [Learning interface](https://github.com/maverickbms/codeguard-pro/blob/main/static/js/codeguard.js): `static/js/codeguard.js`
- [Roadmap views](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/views.py): `apps/roadmaps/views.py`
- [Roadmap services](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services.py): `apps/roadmaps/services.py`
- [Roadmap and progress](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/models.py): `apps/roadmaps/models.py`
- [Assessment engine](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/services_evaluacion.py): `apps/roadmaps/services_evaluacion.py`
- [Evaluation records](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/models_evaluacion.py): `apps/roadmaps/models_evaluacion.py`
- [Local tutor](https://github.com/maverickbms/codeguard-pro/blob/main/apps/tutoring/services.py): `apps/tutoring/services.py`
- [Tutoring sessions](https://github.com/maverickbms/codeguard-pro/blob/main/apps/tutoring/models.py): `apps/tutoring/models.py`

### Knowledge lifecycle

- [Editorial workflow](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/publisher.py): `apps/roadmaps/publisher.py`
- [Content import](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/content_import.py): `apps/roadmaps/content_import.py`
- [Signed packages](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/distribution.py): `apps/roadmaps/distribution.py`
- [Package installer](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/installer.py): `apps/roadmaps/installer.py`
- [Knowledge sync](https://github.com/maverickbms/codeguard-pro/blob/main/apps/roadmaps/sync_client.py): `apps/roadmaps/sync_client.py`

### Practice and rewards

- [Challenges](https://github.com/maverickbms/codeguard-pro/blob/main/apps/challenges/services.py): `apps/challenges/services.py`
- [Gamification](https://github.com/maverickbms/codeguard-pro/blob/main/apps/gamification/services.py): `apps/gamification/services.py`

### Identity and local data

- [Identity services](https://github.com/maverickbms/codeguard-pro/blob/main/apps/accounts/services.py): `apps/accounts/services.py`
- [Audit logging](https://github.com/maverickbms/codeguard-pro/blob/main/apps/audit/services.py): `apps/audit/services.py`
- [Local application data](https://github.com/maverickbms/codeguard-pro/blob/main/config/settings/base.py): `config/settings/base.py`
- [Backup tools](https://github.com/maverickbms/codeguard-pro/blob/main/apps/core/backup.py): `apps/core/backup.py`

### Other components

- **Learner**
- **Ollama local**

## Connections

- Learner → Electron shell: opens app (evidence: `README.md`)
- Electron shell → Local Django server: starts server (evidence: `electron/main.js`)
- Electron shell → Local Django server: checks health (evidence: `electron/main.js`)
- Electron shell → Knowledge sync: starts sync (evidence: `electron/main.js`)
- Learner → Learning interface: studies locally (evidence: `README.md`)
- Learning interface → Roadmap views: uses roadmap
- Roadmap views → Roadmap services: delegates to
- Roadmap services → Roadmap and progress: records progress (evidence: `apps/roadmaps/services.py`)
- Roadmap views → Assessment engine: submits answers
- Assessment engine → Evaluation records: stores results (evidence: `apps/roadmaps/services_evaluacion.py`)
- Assessment engine → Roadmap services: checks criteria (evidence: `apps/roadmaps/services_evaluacion.py`)
- Learner → Local tutor: requests hints (evidence: `README.md`)
- Local tutor → Ollama local: requests explanation (evidence: `apps/tutoring/services.py`)
- Local tutor → Tutoring sessions: stores sessions (evidence: `apps/tutoring/services.py`)
- Content import → Editorial workflow: imports drafts
- Editorial workflow → Signed packages: publishes package (evidence: `README.md`)
- Knowledge sync → Signed packages: verifies package (evidence: `apps/roadmaps/sync_client.py`)
- Knowledge sync → Package installer: installs updates (evidence: `apps/roadmaps/sync_client.py`)
- Package installer → Roadmap and progress: updates catalog (evidence: `apps/roadmaps/installer.py`)
- Learner → Challenges: records result (evidence: `README.md`)
- Challenges → Local application data: persists attempt (evidence: `apps/challenges/services.py`)
- Roadmap services → Gamification: awards progress
- Gamification → Roadmap and progress: reads completion (evidence: `apps/gamification/services.py`)
- Learner → Identity services: authenticates optionally (evidence: `README.md`)
- Identity services → Audit logging: records access events (evidence: `apps/accounts/services.py`)
- Audit logging → Local application data: stores events (evidence: `apps/audit/services.py`)
- Learner → Backup tools: runs backup command (evidence: `README.md`)
- Backup tools → Local application data: backs up database (evidence: `README.md`)
