# mostafawahiep/codearc architecture

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

- Interactive diagram: https://gitdiagram.com/mostafawahiep/codearc
- Repository: https://github.com/mostafawahiep/codearc

## Overview

CodeArc delivers versioned programming challenges through a VS Code extension backed by a Flask progression API. Learners browse challenges, start or resume attempts, edit starter projects, run local tests, and submit results so the backend can advance level progress. The graph separates extension experience, backend API/services, challenge packages, and persistence/domain layers. Backend API handler internals and extension activation wiring were not sampled; those connections are shown only where documented or marked unverified.

Main entry points: [`extension/src/backend/HttpBackendClient.ts`](https://github.com/mostafawahiep/codearc/blob/main/extension/src/backend/HttpBackendClient.ts) (HTTP Backend Client), [`backend/app/infrastructure/file_challenge_repository.py`](https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/file_challenge_repository.py) (Challenge Package Loader), [`backend/app/container.py`](https://github.com/mostafawahiep/codearc/blob/main/backend/app/container.py) (Application Wiring), [`extension/src/views/ChallengeViewProvider.ts`](https://github.com/mostafawahiep/codearc/blob/main/extension/src/views/ChallengeViewProvider.ts) (Challenge Experience)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["VS Code Extension"]
  node_view["Challenge Experience"]
  node_attempt_ui["Attempt Session<br/>[AttemptSession.ts]"]
  node_catalog_ui["Attempt Catalog<br/>[AttemptCatalog.ts]"]
  node_challenge_ui["Challenge Catalog"]
  node_workspace["Learner Workspace"]
  node_local_tests["Local Test Runner<br/>[LocalTestRunner.ts]"]
  node_pytest["Pytest Execution<br/>[PytestRunner.ts]"]
  node_http["HTTP Backend Client"]
end

subgraph group_backend["Backend Services"]
  node_attempt_service["Attempt Progression<br/>[attempt_service.py]"]
  node_challenge_service["Challenge Catalog Service"]
  node_api_attempt["Attempt API<br/>[attempt.py]"]
  node_api_challenge["Challenge API<br/>[challenge.py]"]
  node_container["Application Wiring<br/>[container.py]"]
end

subgraph group_content["Challenge Packages"]
  node_challenge_files["Versioned Challenge Content"]
  node_shared_schema["Shared Contracts<br/>[challenge.ts]"]
end

subgraph group_core["Domain and Persistence"]
  node_challenge_repo["Challenge Repository"]
  node_file_repo["Challenge Package Loader"]
  node_manifest["Manifest Validation"]
  node_attempt_repo["Attempt Repository"]
  node_sql_repo["SQL Attempt Storage"]
  node_attempt_db[("Attempt Database<br/>[attempt_models.py]")]
  node_challenge_domain["Challenge and Level Models<br/>[challenge.py]"]
  node_attempt_domain["Attempt Model<br/>[attempt.py]"]
end

node_learner(("Learner"))
node_vscode["VS Code"]

node_learner -->|"uses"| node_view
node_view -->|"delegates to"| node_attempt_ui
node_view -->|"loads attempts"| node_catalog_ui
node_view -->|"loads challenges"| node_challenge_ui
node_attempt_ui -->|"runs tests"| node_local_tests
node_attempt_ui -->|"manages workspace"| node_workspace
node_attempt_ui -->|"requests backend"| node_http
node_catalog_ui -->|"requests backend"| node_http
node_challenge_ui -->|"requests backend"| node_http
node_local_tests -.->|"executes tests"| node_pytest
node_workspace -->|"fetches starter files"| node_http
node_http -.->|"HTTP requests"| node_api_attempt
node_http -.->|"HTTP requests"| node_api_challenge
node_api_attempt -.->|"dispatches"| node_attempt_service
node_api_challenge -.->|"dispatches"| node_challenge_service
node_attempt_service -->|"reads and writes"| node_attempt_repo
node_attempt_service -->|"loads challenge data"| node_challenge_repo
node_challenge_service -->|"loads challenge data"| node_challenge_repo
node_container -->|"configures"| node_attempt_service
node_container -->|"configures"| node_challenge_service
node_container -->|"configures"| node_file_repo
node_container -->|"configures"| node_sql_repo
node_file_repo -->|"validates manifests"| node_manifest
node_file_repo -->|"loads definitions"| node_challenge_domain
node_challenge_repo -->|"implemented by"| node_file_repo
node_attempt_repo -->|"implemented by"| node_sql_repo
node_sql_repo -->|"maps and persists"| node_attempt_db
node_sql_repo -->|"maps attempts"| node_attempt_domain
node_challenge_files -.->|"loaded from packages"| node_file_repo
node_shared_schema -.->|"defines contracts"| node_http
node_vscode -->|"hosts workspace"| node_workspace

click node_view "https://github.com/mostafawahiep/codearc/blob/main/extension/src/views/ChallengeViewProvider.ts"
click node_attempt_ui "https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/AttemptSession.ts"
click node_catalog_ui "https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/AttemptCatalog.ts"
click node_challenge_ui "https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/ChallengeCatalog.ts"
click node_workspace "https://github.com/mostafawahiep/codearc/blob/main/extension/src/infrastructure/LearnerWorkspaceService.ts"
click node_local_tests "https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/LocalTestRunner.ts"
click node_pytest "https://github.com/mostafawahiep/codearc/blob/main/extension/src/infrastructure/PytestRunner.ts"
click node_http "https://github.com/mostafawahiep/codearc/blob/main/extension/src/backend/HttpBackendClient.ts"
click node_attempt_service "https://github.com/mostafawahiep/codearc/blob/main/backend/app/services/attempt_service.py"
click node_challenge_service "https://github.com/mostafawahiep/codearc/blob/main/backend/app/services/challenge_service.py"
click node_api_attempt "https://github.com/mostafawahiep/codearc/blob/main/backend/app/api/v1/attempt.py"
click node_api_challenge "https://github.com/mostafawahiep/codearc/blob/main/backend/app/api/v1/challenge.py"
click node_container "https://github.com/mostafawahiep/codearc/blob/main/backend/app/container.py"
click node_challenge_repo "https://github.com/mostafawahiep/codearc/blob/main/backend/app/repositories/challenge_repository.py"
click node_file_repo "https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/file_challenge_repository.py"
click node_manifest "https://github.com/mostafawahiep/codearc/blob/main/backend/app/validation/manifest_validator.py"
click node_attempt_repo "https://github.com/mostafawahiep/codearc/blob/main/backend/app/repositories/attempt_repository.py"
click node_sql_repo "https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/sqlalchemy_attempt_repository.py"
click node_attempt_db "https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/database/attempt_models.py"
click node_challenge_domain "https://github.com/mostafawahiep/codearc/blob/main/backend/app/domain/challenge.py"
click node_attempt_domain "https://github.com/mostafawahiep/codearc/blob/main/backend/app/domain/attempt.py"
click node_challenge_files "https://github.com/mostafawahiep/codearc/tree/main/challenges/search-engine/v1"
click node_shared_schema "https://github.com/mostafawahiep/codearc/blob/main/shared/src/challenge.ts"

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_view,node_attempt_ui,node_catalog_ui,node_challenge_ui,node_workspace,node_local_tests,node_pytest,node_http toneBlue
class node_attempt_service,node_challenge_service,node_api_attempt,node_api_challenge,node_container toneAmber
class node_challenge_files,node_shared_schema toneMint
class node_challenge_repo,node_file_repo,node_manifest,node_attempt_repo,node_sql_repo,node_attempt_db,node_challenge_domain,node_attempt_domain toneRose
class node_learner,node_vscode toneIndigo
```

## Components

### VS Code Extension

- [Challenge Experience](https://github.com/mostafawahiep/codearc/blob/main/extension/src/views/ChallengeViewProvider.ts): `extension/src/views/ChallengeViewProvider.ts`
- [Attempt Session](https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/AttemptSession.ts): `extension/src/application/AttemptSession.ts`
- [Attempt Catalog](https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/AttemptCatalog.ts): `extension/src/application/AttemptCatalog.ts`
- [Challenge Catalog](https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/ChallengeCatalog.ts): `extension/src/application/ChallengeCatalog.ts`
- [Learner Workspace](https://github.com/mostafawahiep/codearc/blob/main/extension/src/infrastructure/LearnerWorkspaceService.ts): `extension/src/infrastructure/LearnerWorkspaceService.ts`
- [Local Test Runner](https://github.com/mostafawahiep/codearc/blob/main/extension/src/application/LocalTestRunner.ts): `extension/src/application/LocalTestRunner.ts`
- [Pytest Execution](https://github.com/mostafawahiep/codearc/blob/main/extension/src/infrastructure/PytestRunner.ts): `extension/src/infrastructure/PytestRunner.ts`
- [HTTP Backend Client](https://github.com/mostafawahiep/codearc/blob/main/extension/src/backend/HttpBackendClient.ts): `extension/src/backend/HttpBackendClient.ts`

### Backend Services

- [Attempt Progression](https://github.com/mostafawahiep/codearc/blob/main/backend/app/services/attempt_service.py): `backend/app/services/attempt_service.py`
- [Challenge Catalog Service](https://github.com/mostafawahiep/codearc/blob/main/backend/app/services/challenge_service.py): `backend/app/services/challenge_service.py`
- [Attempt API](https://github.com/mostafawahiep/codearc/blob/main/backend/app/api/v1/attempt.py): `backend/app/api/v1/attempt.py`
- [Challenge API](https://github.com/mostafawahiep/codearc/blob/main/backend/app/api/v1/challenge.py): `backend/app/api/v1/challenge.py`
- [Application Wiring](https://github.com/mostafawahiep/codearc/blob/main/backend/app/container.py): `backend/app/container.py`

### Challenge Packages

- [Versioned Challenge Content](https://github.com/mostafawahiep/codearc/tree/main/challenges/search-engine/v1): `challenges/search-engine/v1`
- [Shared Contracts](https://github.com/mostafawahiep/codearc/blob/main/shared/src/challenge.ts): `shared/src/challenge.ts`

### Domain and Persistence

- [Challenge Repository](https://github.com/mostafawahiep/codearc/blob/main/backend/app/repositories/challenge_repository.py): `backend/app/repositories/challenge_repository.py`
- [Challenge Package Loader](https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/file_challenge_repository.py): `backend/app/infrastructure/file_challenge_repository.py`
- [Manifest Validation](https://github.com/mostafawahiep/codearc/blob/main/backend/app/validation/manifest_validator.py): `backend/app/validation/manifest_validator.py`
- [Attempt Repository](https://github.com/mostafawahiep/codearc/blob/main/backend/app/repositories/attempt_repository.py): `backend/app/repositories/attempt_repository.py`
- [SQL Attempt Storage](https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/sqlalchemy_attempt_repository.py): `backend/app/infrastructure/sqlalchemy_attempt_repository.py`
- [Attempt Database](https://github.com/mostafawahiep/codearc/blob/main/backend/app/infrastructure/database/attempt_models.py): `backend/app/infrastructure/database/attempt_models.py`
- [Challenge and Level Models](https://github.com/mostafawahiep/codearc/blob/main/backend/app/domain/challenge.py): `backend/app/domain/challenge.py`
- [Attempt Model](https://github.com/mostafawahiep/codearc/blob/main/backend/app/domain/attempt.py): `backend/app/domain/attempt.py`

### Other components

- **Learner**
- **VS Code**

## Connections

- Learner → Challenge Experience: uses (evidence: `README.md`)
- Challenge Experience → Attempt Session: delegates to (evidence: `extension/src/views/ChallengeViewProvider.ts`)
- Challenge Experience → Attempt Catalog: loads attempts (evidence: `extension/src/views/ChallengeViewProvider.ts`)
- Challenge Experience → Challenge Catalog: loads challenges (evidence: `extension/src/views/ChallengeViewProvider.ts`)
- Attempt Session → Local Test Runner: runs tests (evidence: `extension/src/application/AttemptSession.ts`)
- Attempt Session → Learner Workspace: manages workspace (evidence: `extension/src/views/ChallengeViewProvider.ts`)
- Attempt Session → HTTP Backend Client: requests backend (evidence: `extension/src/application/AttemptSession.ts`)
- Attempt Catalog → HTTP Backend Client: requests backend (evidence: `extension/src/application/AttemptCatalog.ts`)
- Challenge Catalog → HTTP Backend Client: requests backend (evidence: `extension/src/application/ChallengeCatalog.ts`)
- Local Test Runner → Pytest Execution: executes tests
- Learner Workspace → HTTP Backend Client: fetches starter files (evidence: `extension/src/infrastructure/LearnerWorkspaceService.ts`)
- HTTP Backend Client → Attempt API: HTTP requests
- HTTP Backend Client → Challenge API: HTTP requests
- Attempt API → Attempt Progression: dispatches
- Challenge API → Challenge Catalog Service: dispatches
- Attempt Progression → Attempt Repository: reads and writes (evidence: `backend/app/services/attempt_service.py`)
- Attempt Progression → Challenge Repository: loads challenge data (evidence: `backend/app/services/attempt_service.py`)
- Challenge Catalog Service → Challenge Repository: loads challenge data (evidence: `backend/app/services/challenge_service.py`)
- Application Wiring → Attempt Progression: configures (evidence: `backend/app/container.py`)
- Application Wiring → Challenge Catalog Service: configures (evidence: `backend/app/container.py`)
- Application Wiring → Challenge Package Loader: configures (evidence: `backend/app/container.py`)
- Application Wiring → SQL Attempt Storage: configures (evidence: `backend/app/container.py`)
- Challenge Package Loader → Manifest Validation: validates manifests (evidence: `backend/app/infrastructure/file_challenge_repository.py`)
- Challenge Package Loader → Challenge and Level Models: loads definitions (evidence: `backend/app/infrastructure/file_challenge_repository.py`)
- Challenge Repository → Challenge Package Loader: implemented by (evidence: `backend/app/infrastructure/file_challenge_repository.py`)
- Attempt Repository → SQL Attempt Storage: implemented by (evidence: `backend/app/infrastructure/sqlalchemy_attempt_repository.py`)
- SQL Attempt Storage → Attempt Database: maps and persists (evidence: `backend/app/infrastructure/sqlalchemy_attempt_repository.py`)
- SQL Attempt Storage → Attempt Model: maps attempts (evidence: `backend/app/infrastructure/sqlalchemy_attempt_repository.py`)
- Versioned Challenge Content → Challenge Package Loader: loaded from packages
- Shared Contracts → HTTP Backend Client: defines contracts
- VS Code → Learner Workspace: hosts workspace (evidence: `extension/src/infrastructure/LearnerWorkspaceService.ts`)
