# akash0826/smartreco architecture

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

- Interactive diagram: https://gitdiagram.com/akash0826/smartreco
- Repository: https://github.com/akash0826/smartreco

## Overview

SmartReco is an event-driven learning platform whose main journey runs from learner interactions through behavioral tracking and gamification thresholds to LangGraph recommendations, then presents a personalized learning path. Admin catalog changes feed both relational and semantic search storage; authentication, course enrollment, and scheduled recommendation digests are supporting product flows. The README documents the overall design, while sampled source confirms key calls; some components, including the gamification engine, are only partially visible or unsampled.

Main entry points: [`app/services/recommendation_service.py`](https://github.com/akash0826/smartreco/blob/master/app/services/recommendation_service.py) (Recommendation Service), [`app/api/routes_views.py`](https://github.com/akash0826/smartreco/blob/master/app/api/routes_views.py) (Learning Views), [`app/tasks/pattern_tasks.py`](https://github.com/akash0826/smartreco/blob/master/app/tasks/pattern_tasks.py) (Pattern Tasks), [`app/api/routes_auth.py`](https://github.com/akash0826/smartreco/blob/master/app/api/routes_auth.py) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner Experience"]
  node_tracker["Interaction Tracker<br/>[tracker.js]"]
  node_tracking_routes["Tracking API<br/>[routes_tracking.py]"]
  node_webhook_routes["Tracking Webhooks<br/>[routes_webhooks.py]"]
  node_views["Learning Views<br/>[routes_views.py]"]
  node_enrollments["Enrollments<br/>[enrollment.py]"]
end

subgraph group_behavior["Behavior And Recommendations"]
  node_events["Behavior Events<br/>[event.py]"]
  node_recommendation_records["Recommendation Records<br/>[recommendation.py]"]
  node_tracking_service["Tracking Logic"]
  node_recommendation_service["Recommendation Service"]
  node_workflow["Agent Workflow<br/>[workflow.py]"]
  node_agent_nodes["Reasoning Nodes<br/>[nodes.py]"]
  node_retriever["Semantic Retriever<br/>[retriever.py]"]
  node_gamification["Gamification Engine"]
  node_behavioral_rules["Behavior Rules<br/>[behavioral_rule.py]"]
end

subgraph group_catalog["Catalog And Retrieval"]
  node_products["Course Catalog Records<br/>[product.py]"]
  node_catalog_service["Catalog Service<br/>[catalog_service.py]"]
  node_lancedb[("LanceDB Catalog<br/>[lancedb_client.py]")]
end

subgraph group_identity["Identity And Persistence"]
  node_auth_routes["Authentication API<br/>[routes_auth.py]"]
  node_auth_service["Password Verification<br/>[auth_service.py]"]
  node_users["User Records<br/>[user.py]"]
  node_postgres[("PostgreSQL<br/>[postgres_db.py]")]
end

subgraph group_operations["Background Operations"]
  node_pattern_tasks["Pattern Tasks<br/>[pattern_tasks.py]"]
  node_execution_logger["Execution Logger"]
  node_trace_writer["Trace Writer"]
  node_agent_tasks["Agent Tasks<br/>[agent_tasks.py]"]
  node_email_tasks["Recommendation Digests<br/>[email_tasks.py]"]
end

node_learner(("Learner"))
node_admin(("Administrator"))
node_mesh["Mesh API"]

node_learner -->|"interacts with"| node_tracker
node_tracker -->|"posts batches"| node_tracking_routes
node_tracking_routes -->|"processes events"| node_tracking_service
node_webhook_routes -->|"processes events"| node_tracking_service
node_tracking_service -->|"records telemetry"| node_events
node_tracking_routes -->|"triggers refresh"| node_recommendation_service
node_views -->|"reads and updates"| node_enrollments
node_views -->|"reads courses"| node_products
node_views -->|"loads recommendations"| node_recommendation_service
node_views -->|"requests refresh"| node_recommendation_service
node_recommendation_service -->|"reads recent activity"| node_events
node_recommendation_service -->|"invokes agent"| node_workflow
node_workflow -->|"dispatches nodes"| node_agent_nodes
node_agent_nodes -->|"retrieves matches"| node_retriever
node_retriever -.->|"searches catalog"| node_lancedb
node_retriever -.->|"requests embeddings"| node_mesh
node_recommendation_service -->|"stores result"| node_recommendation_records
node_admin -->|"manages catalog"| node_catalog_service
node_catalog_service -->|"writes catalog"| node_products
node_catalog_service -->|"dual-writes vectors"| node_lancedb
node_auth_routes -->|"verifies password"| node_auth_service
node_auth_routes -->|"loads account"| node_users
node_auth_routes -->|"queries user"| node_postgres
node_views -->|"queries records"| node_postgres
node_pattern_tasks -->|"evaluates patterns"| node_gamification
node_pattern_tasks -->|"reads rules"| node_behavioral_rules
node_pattern_tasks -->|"records execution"| node_execution_logger
node_pattern_tasks -->|"writes traces"| node_trace_writer
node_agent_tasks -->|"generates paths"| node_recommendation_service
node_email_tasks -->|"reads pending"| node_recommendation_records
node_email_tasks -->|"loads course details"| node_products
node_email_tasks -->|"reads recipients"| node_users

click node_tracker "https://github.com/akash0826/smartreco/blob/master/app/static/js/tracker.js"
click node_tracking_routes "https://github.com/akash0826/smartreco/blob/master/app/api/routes_tracking.py"
click node_webhook_routes "https://github.com/akash0826/smartreco/blob/master/app/api/routes_webhooks.py"
click node_views "https://github.com/akash0826/smartreco/blob/master/app/api/routes_views.py"
click node_auth_routes "https://github.com/akash0826/smartreco/blob/master/app/api/routes_auth.py"
click node_auth_service "https://github.com/akash0826/smartreco/blob/master/app/services/auth_service.py"
click node_users "https://github.com/akash0826/smartreco/blob/master/app/models/user.py"
click node_events "https://github.com/akash0826/smartreco/blob/master/app/models/event.py"
click node_enrollments "https://github.com/akash0826/smartreco/blob/master/app/models/enrollment.py"
click node_products "https://github.com/akash0826/smartreco/blob/master/app/models/product.py"
click node_recommendation_records "https://github.com/akash0826/smartreco/blob/master/app/models/recommendation.py"
click node_tracking_service "https://github.com/akash0826/smartreco/blob/master/app/services/tracking_service.py"
click node_recommendation_service "https://github.com/akash0826/smartreco/blob/master/app/services/recommendation_service.py"
click node_workflow "https://github.com/akash0826/smartreco/blob/master/app/agent/workflow.py"
click node_agent_nodes "https://github.com/akash0826/smartreco/blob/master/app/agent/nodes.py"
click node_retriever "https://github.com/akash0826/smartreco/blob/master/app/agent/retriever.py"
click node_catalog_service "https://github.com/akash0826/smartreco/blob/master/app/services/catalog_service.py"
click node_postgres "https://github.com/akash0826/smartreco/blob/master/app/core/postgres_db.py"
click node_lancedb "https://github.com/akash0826/smartreco/blob/master/app/core/lancedb_client.py"
click node_gamification "https://github.com/akash0826/smartreco/blob/master/app/core/smartreco_engine.py"
click node_behavioral_rules "https://github.com/akash0826/smartreco/blob/master/app/models/behavioral_rule.py"
click node_pattern_tasks "https://github.com/akash0826/smartreco/blob/master/app/tasks/pattern_tasks.py"
click node_execution_logger "https://github.com/akash0826/smartreco/blob/master/Logger/Execution_Logger.py"
click node_trace_writer "https://github.com/akash0826/smartreco/blob/master/Logger/enterprise_trace_writer.py"
click node_agent_tasks "https://github.com/akash0826/smartreco/blob/master/app/tasks/agent_tasks.py"
click node_email_tasks "https://github.com/akash0826/smartreco/blob/master/app/tasks/email_tasks.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_tracker,node_tracking_routes,node_webhook_routes,node_views,node_enrollments toneBlue
class node_events,node_recommendation_records,node_tracking_service,node_recommendation_service,node_workflow,node_agent_nodes,node_retriever,node_gamification,node_behavioral_rules toneAmber
class node_products,node_catalog_service,node_lancedb,node_mesh toneMint
class node_auth_routes,node_auth_service,node_users,node_postgres toneRose
class node_pattern_tasks,node_execution_logger,node_trace_writer,node_agent_tasks,node_email_tasks,node_learner,node_admin toneIndigo
```

## Components

### Learner Experience

- [Interaction Tracker](https://github.com/akash0826/smartreco/blob/master/app/static/js/tracker.js): `app/static/js/tracker.js`
- [Tracking API](https://github.com/akash0826/smartreco/blob/master/app/api/routes_tracking.py): `app/api/routes_tracking.py`
- [Tracking Webhooks](https://github.com/akash0826/smartreco/blob/master/app/api/routes_webhooks.py): `app/api/routes_webhooks.py`
- [Learning Views](https://github.com/akash0826/smartreco/blob/master/app/api/routes_views.py): `app/api/routes_views.py`
- [Enrollments](https://github.com/akash0826/smartreco/blob/master/app/models/enrollment.py): `app/models/enrollment.py`

### Behavior And Recommendations

- [Behavior Events](https://github.com/akash0826/smartreco/blob/master/app/models/event.py): `app/models/event.py`
- [Recommendation Records](https://github.com/akash0826/smartreco/blob/master/app/models/recommendation.py): `app/models/recommendation.py`
- [Tracking Logic](https://github.com/akash0826/smartreco/blob/master/app/services/tracking_service.py): `app/services/tracking_service.py`
- [Recommendation Service](https://github.com/akash0826/smartreco/blob/master/app/services/recommendation_service.py): `app/services/recommendation_service.py`
- [Agent Workflow](https://github.com/akash0826/smartreco/blob/master/app/agent/workflow.py): `app/agent/workflow.py`
- [Reasoning Nodes](https://github.com/akash0826/smartreco/blob/master/app/agent/nodes.py): `app/agent/nodes.py`
- [Semantic Retriever](https://github.com/akash0826/smartreco/blob/master/app/agent/retriever.py): `app/agent/retriever.py`
- [Gamification Engine](https://github.com/akash0826/smartreco/blob/master/app/core/smartreco_engine.py): `app/core/smartreco_engine.py`
- [Behavior Rules](https://github.com/akash0826/smartreco/blob/master/app/models/behavioral_rule.py): `app/models/behavioral_rule.py`

### Catalog And Retrieval

- [Course Catalog Records](https://github.com/akash0826/smartreco/blob/master/app/models/product.py): `app/models/product.py`
- [Catalog Service](https://github.com/akash0826/smartreco/blob/master/app/services/catalog_service.py): `app/services/catalog_service.py`
- [LanceDB Catalog](https://github.com/akash0826/smartreco/blob/master/app/core/lancedb_client.py): `app/core/lancedb_client.py`

### Identity And Persistence

- [Authentication API](https://github.com/akash0826/smartreco/blob/master/app/api/routes_auth.py): `app/api/routes_auth.py`
- [Password Verification](https://github.com/akash0826/smartreco/blob/master/app/services/auth_service.py): `app/services/auth_service.py`
- [User Records](https://github.com/akash0826/smartreco/blob/master/app/models/user.py): `app/models/user.py`
- [PostgreSQL](https://github.com/akash0826/smartreco/blob/master/app/core/postgres_db.py): `app/core/postgres_db.py`

### Background Operations

- [Pattern Tasks](https://github.com/akash0826/smartreco/blob/master/app/tasks/pattern_tasks.py): `app/tasks/pattern_tasks.py`
- [Execution Logger](https://github.com/akash0826/smartreco/blob/master/Logger/Execution_Logger.py): `Logger/Execution_Logger.py`
- [Trace Writer](https://github.com/akash0826/smartreco/blob/master/Logger/enterprise_trace_writer.py): `Logger/enterprise_trace_writer.py`
- [Agent Tasks](https://github.com/akash0826/smartreco/blob/master/app/tasks/agent_tasks.py): `app/tasks/agent_tasks.py`
- [Recommendation Digests](https://github.com/akash0826/smartreco/blob/master/app/tasks/email_tasks.py): `app/tasks/email_tasks.py`

### Other components

- **Learner**
- **Administrator**
- **Mesh API**

## Connections

- Learner → Interaction Tracker: interacts with
- Interaction Tracker → Tracking API: posts batches
- Tracking API → Tracking Logic: processes events (evidence: `app/api/routes_tracking.py`)
- Tracking Webhooks → Tracking Logic: processes events (evidence: `app/api/routes_webhooks.py`)
- Tracking Logic → Behavior Events: records telemetry (evidence: `app/services/tracking_service.py`)
- Tracking API → Recommendation Service: triggers refresh (evidence: `app/api/routes_tracking.py`)
- Learning Views → Enrollments: reads and updates (evidence: `app/api/routes_views.py`)
- Learning Views → Course Catalog Records: reads courses (evidence: `app/api/routes_views.py`)
- Learning Views → Recommendation Service: loads recommendations (evidence: `app/api/routes_views.py`)
- Learning Views → Recommendation Service: requests refresh (evidence: `app/api/routes_views.py`)
- Recommendation Service → Behavior Events: reads recent activity (evidence: `app/services/recommendation_service.py`)
- Recommendation Service → Agent Workflow: invokes agent (evidence: `app/services/recommendation_service.py`)
- Agent Workflow → Reasoning Nodes: dispatches nodes (evidence: `app/agent/workflow.py`)
- Reasoning Nodes → Semantic Retriever: retrieves matches (evidence: `app/agent/nodes.py`)
- Semantic Retriever → LanceDB Catalog: searches catalog
- Semantic Retriever → Mesh API: requests embeddings
- Recommendation Service → Recommendation Records: stores result (evidence: `app/services/recommendation_service.py`)
- Administrator → Catalog Service: manages catalog
- Catalog Service → Course Catalog Records: writes catalog (evidence: `app/services/catalog_service.py`)
- Catalog Service → LanceDB Catalog: dual-writes vectors (evidence: `app/services/catalog_service.py`)
- Authentication API → Password Verification: verifies password (evidence: `app/api/routes_auth.py`)
- Authentication API → User Records: loads account (evidence: `app/api/routes_auth.py`)
- Authentication API → PostgreSQL: queries user (evidence: `app/api/routes_auth.py`)
- Learning Views → PostgreSQL: queries records (evidence: `app/api/routes_views.py`)
- Pattern Tasks → Gamification Engine: evaluates patterns (evidence: `app/tasks/pattern_tasks.py`)
- Pattern Tasks → Behavior Rules: reads rules (evidence: `app/tasks/pattern_tasks.py`)
- Pattern Tasks → Execution Logger: records execution (evidence: `app/tasks/pattern_tasks.py`)
- Pattern Tasks → Trace Writer: writes traces (evidence: `app/tasks/pattern_tasks.py`)
- Agent Tasks → Recommendation Service: generates paths (evidence: `app/tasks/agent_tasks.py`)
- Recommendation Digests → Recommendation Records: reads pending (evidence: `app/tasks/email_tasks.py`)
- Recommendation Digests → Course Catalog Records: loads course details (evidence: `app/tasks/email_tasks.py`)
- Recommendation Digests → User Records: reads recipients (evidence: `app/tasks/email_tasks.py`)
