How akash0826/smartreco works
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: recommendation_service.py Recommendation Service · routes_views.py Learning Views · pattern_tasks.py Pattern Tasks · routes_auth.py Authentication API
Components 29
Learner Experience
- Interaction Tracker
app/static/js/tracker.js - Tracking API
app/api/routes_tracking.py - Tracking Webhooks
app/api/routes_webhooks.py - Learning Views
app/api/routes_views.py - Enrollments
app/models/enrollment.py
Behavior And Recommendations
- Behavior Events
app/models/event.py - Recommendation Records
app/models/recommendation.py - Tracking Logic
app/services/tracking_service.py - Recommendation Service
app/services/recommendation_service.py - Agent Workflow
app/agent/workflow.py - Reasoning Nodes
app/agent/nodes.py - Semantic Retriever
app/agent/retriever.py - Gamification Engine
app/core/smartreco_engine.py - Behavior Rules
app/models/behavioral_rule.py
Catalog And Retrieval
- Course Catalog Records
app/models/product.py - Catalog Service
app/services/catalog_service.py - LanceDB Catalog
app/core/lancedb_client.py
Identity And Persistence
- Authentication API
app/api/routes_auth.py - Password Verification
app/services/auth_service.py - User Records
app/models/user.py - PostgreSQL
app/core/postgres_db.py
Background Operations
- Pattern Tasks
app/tasks/pattern_tasks.py - Execution Logger
Logger/Execution_Logger.py - Trace Writer
Logger/enterprise_trace_writer.py - Agent Tasks
app/tasks/agent_tasks.py - Recommendation Digests
app/tasks/email_tasks.py
Other components
- Learner
- Administrator
- Mesh API
Connections 32
- Learner → Interaction Tracker: interacts with
- Interaction Tracker → Tracking API: posts batches
- Tracking API → Tracking Logic: processes events
app/api/routes_tracking.py - Tracking Webhooks → Tracking Logic: processes events
app/api/routes_webhooks.py - Tracking Logic → Behavior Events: records telemetry
app/services/tracking_service.py - Tracking API → Recommendation Service: triggers refresh
app/api/routes_tracking.py - Learning Views → Enrollments: reads and updates
app/api/routes_views.py - Learning Views → Course Catalog Records: reads courses
app/api/routes_views.py - Learning Views → Recommendation Service: loads recommendations
app/api/routes_views.py - Learning Views → Recommendation Service: requests refresh
app/api/routes_views.py - Recommendation Service → Behavior Events: reads recent activity
app/services/recommendation_service.py - Recommendation Service → Agent Workflow: invokes agent
app/services/recommendation_service.py - Agent Workflow → Reasoning Nodes: dispatches nodes
app/agent/workflow.py - Reasoning Nodes → Semantic Retriever: retrieves matches
app/agent/nodes.py - Semantic Retriever → LanceDB Catalog: searches catalog
- Semantic Retriever → Mesh API: requests embeddings
- Recommendation Service → Recommendation Records: stores result
app/services/recommendation_service.py - Administrator → Catalog Service: manages catalog
- Catalog Service → Course Catalog Records: writes catalog
app/services/catalog_service.py - Catalog Service → LanceDB Catalog: dual-writes vectors
app/services/catalog_service.py - Authentication API → Password Verification: verifies password
app/api/routes_auth.py - Authentication API → User Records: loads account
app/api/routes_auth.py - Authentication API → PostgreSQL: queries user
app/api/routes_auth.py - Learning Views → PostgreSQL: queries records
app/api/routes_views.py - Pattern Tasks → Gamification Engine: evaluates patterns
app/tasks/pattern_tasks.py - Pattern Tasks → Behavior Rules: reads rules
app/tasks/pattern_tasks.py - Pattern Tasks → Execution Logger: records execution
app/tasks/pattern_tasks.py - Pattern Tasks → Trace Writer: writes traces
app/tasks/pattern_tasks.py - Agent Tasks → Recommendation Service: generates paths
app/tasks/agent_tasks.py - Recommendation Digests → Recommendation Records: reads pending
app/tasks/email_tasks.py - Recommendation Digests → Course Catalog Records: loads course details
app/tasks/email_tasks.py - Recommendation Digests → User Records: reads recipients
app/tasks/email_tasks.py