idodo-t/fellah-ai

Purpose and Entry Points

The repository appears to implement a “Fellah AI” assistant for agricultural/productivity workflows: user profiles, products, profitability, cash tracking, recommendations, and multimodal interaction. Primary application entry points are app/main.py for the backend service and dashboard/app.py for a separate operator/user dashboard.

Application Core

app/main.py is the likely API/application composition boundary, delegating domain work into app/services/. Shared persistence access is centralized in app/database.py, while cross-cutting utilities reside in app/utils.py. The backend should remain the control-plane boundary between dashboard/client requests, AI integrations, and local data.

Paths: app/main.py, app/database.py, app/utils.py

Domain Services

Business capabilities are separated into focused service modules:

• Product and farm/catalog operations: app/services/products.py

• User/farmer profile handling: app/services/profile.py

• Cash-flow recording or analysis: app/services/fell_cash.py

• Profitability calculation/analysis: app/services/profit.py

• Recommendation generation: app/services/recommender.py

A typical flow is request → profile/product/financial retrieval → profit or recommendation computation → response persisted or returned through the main application.

Agent and AI Orchestration

app/services/agents.py is the likely orchestration layer for agentic workflows, coordinating domain context with recommendation or conversational capabilities. It forms an important boundary: domain services should provide structured farm, product, and financial context, while agents decide how to synthesize it into guidance.

Paths: app/services/agents.py, app/services/recommender.py, app/services/profit.py

Multimodal Interaction Pipeline

Voice, text-to-speech, and vision are isolated as integration services:

• Speech/audio input processing: app/services/voice.py

• Spoken response generation: app/services/tts.py

• Image or camera-based analysis: app/services/vision.py

These modules likely connect the application to external AI/media APIs or local model runtimes. Their outputs should enter the same agent/domain pipeline rather than directly owning business-state changes.

Data and Runtime Boundaries

The checked-in fellah_ai.db indicates a local SQLite-style persistent store, accessed through app/database.py. requirements.txt defines the Python runtime dependencies. ngrok.exe suggests development-time public tunneling for exposing the backend or dashboard to remote/mobile clients; it is infrastructure support rather than core application logic.

Paths: fellah_ai.db, app/database.py, requirements.txt

Dashboard Boundary

dashboard/app.py is a distinct presentation/runtime surface. It should consume backend/domain outputs rather than duplicate service logic. This separation permits the backend to support other clients—such as voice, mobile, or external integrations—while the dashboard focuses on visualization and operator interaction.

Paths: dashboard/app.py, app/main.py