How eltacher/yzta-5.0_ai_hackathon works
1. Project shape
- YZTA is a two-tier e-commerce operations platform: a browser-based SPA in frontend/ and a FastAPI backend in backend/.
- The backend is the central integration point; the frontend is mostly a thin client that calls REST endpoints and likely consumes real-time updates.
2. Primary runtime boundaries
- Frontend boundary: static HTML/CSS/vanilla JS modules (index.html, js/*.js) handle screen rendering and user actions.
- Backend boundary: FastAPI exposes the application API and AI endpoints through router modules.
- Persistence boundary: SQLite (yzta_ecommerce.db) accessed through SQLAlchemy models in models.py.
3. Backend composition
- main.py is the application entrypoint and likely wires together routers, static serving, and WebSocket support.
- database.py defines the DB connection/session layer.
- models.py defines the domain schema for products, orders, customers, cargo, inventory, tasks, and analytics-related records.
4. API layer
- The backend is split by domain into routers:
- products.py, orders.py, customers.py
- cargo.py, inventory.py, tasks.py
- analytics.py
- ai_chat.py
- This suggests a clear REST-style boundary where each business area owns its own endpoints rather than one monolithic controller.
5. Service layer
- Business logic is separated from request handling in backend/services/.
- inventory_service.py, cargo_service.py, and workflow_service.py likely encapsulate cross-route rules and automation.
- notification_service.py suggests event-driven side effects such as alerts or reminders, probably triggered from inventory, cargo, or workflow logic.
- ai_agent.py is the AI orchestration layer used by the chat module and possibly analytics recommendations.
6. AI-assisted subsystem
- The README describes a Gemini-backed AI agent with “mock mode” support.
- The AI flow appears to be: user message in the chat UI → ai_chat router → ai_agent service → database context gathering → generated response and/or action.
- The agent is used for intent detection, contextual lookup, and response generation rather than as a generic chat model only.
7. Operational workflows
- The repo is structured around business operations: stock monitoring, order status, cargo tracking, task generation, and sales analysis.
- workflow_service.py likely connects these domains by creating tasks or triggers from operational events.
- notification_service.py likely acts as the outbound edge for low-stock alerts, delayed cargo warnings, or task assignments.
8. Frontend structure
- The SPA is modularized by feature: dashboard.js, orders.js, products.js, customers.js, inventory.js, cargo.js, tasks.js, analytics.js, and chat.js.
- api.js centralizes backend calls, while components.js likely contains reusable UI pieces.
- app.js is the client bootstrapping/orchestration layer.
9. Frontend-to-backend data flow
- User interactions in the SPA call the backend through api.js.
- Each feature module maps to a backend router, keeping UI and API boundaries aligned by domain.
- Analytics and chat are special paths: analytics likely fetches aggregates/predictions, while chat sends natural-language queries that are resolved server-side.
10. Data and initialization
- seed_data.py indicates the app is designed to be initialized with demo data for hackathon/demo use.
- The presence of a checked-in SQLite database file suggests the repository is self-contained and optimized for local startup without external infrastructure.
11. External integration
- The only explicit external dependency called out in the README is Google Gemini API for AI features.
- Everything else appears local-first: FastAPI, SQLite, and static frontend assets.
12. Architecture diagram takeaway
- When drawing the system, represent:
- a browser SPA on the left,
- FastAPI routers in the middle,
- service-layer business logic beneath the routers,
- SQLite/SQLAlchemy at the bottom,
- and a separate AI integration path through ai_agent that feeds the chat and recommendation flows.
Main entry points: app.js App shell · routers REST routers · services Services · api.js API client
Components 18
Frontend SPA
Browser-side interface and feature modules
- App shell · Initializes the browser app and coordinates feature modules
frontend/js/app.js - API client · Centralizes calls from the SPA to backend endpoints
frontend/js/api.js - UI components · Reusable presentation pieces used across screens
frontend/js/components.js - Dashboard · Operational overview and summary screens
frontend/js/dashboard.js - Orders UI · Order management screens and actions
frontend/js/orders.js - Inventory UI · Stock and inventory management screens
frontend/js/inventory.js - Chat UI · Natural-language interaction surface for AI-assisted operations
frontend/js/chat.js
FastAPI Backend
API, orchestration, and server entrypoint
- App entry · Wires routers, static serving, and server startup
backend/main.py - DB session · Database connection and session management
backend/database.py - Domain models · Products, orders, customers, cargo, inventory, tasks, and analytics records
backend/models.py - REST routers · Domain-specific HTTP endpoints for business operations
backend/routers - Services · Cross-route rules, workflows, and notifications
backend/services - Chat router · Backend entrypoint for AI chat requests
backend/routers/ai_chat.py - Workflow service · Coordinates operational triggers, task creation, and business flows
backend/services/workflow_service.py - Notifications · Emits alerts and operational reminders
backend/services/notification_service.py
Data Layer
SQLite persistence and seeded demo data
AI Integration
Chat and agent orchestration path
- AI agent · Interprets chat intent, gathers context, and generates responses
backend/services/ai_agent.py
Connections 28
- App shell → API client: uses · Bootstrapped UI delegates backend calls through the shared client
- App shell → UI components: composes · App shell assembles reusable UI pieces
- App shell → Dashboard: loads · Navigates to operational dashboard views
- App shell → Orders UI: loads · Navigates to order management views
- App shell → Inventory UI: loads · Navigates to inventory views
- App shell → Chat UI: loads · Opens AI chat experience
- Dashboard → API client: fetches · Dashboard pulls aggregates and operational status
- Orders UI → API client: fetches · Order screens read and update backend resources
- Inventory UI → API client: fetches · Inventory screens read stock state and submit actions
- Chat UI → API client: sends · Chat UI submits user prompts to the backend
- App entry → REST routers: mounts · Application entrypoint registers domain routers
- App entry → DB session: configures · Server initialization attaches persistence layer
- App entry → Services: orchestrates · Main app wires business services into runtime flows
- REST routers → Domain models: uses · Routers read and write domain entities
- REST routers → DB session: queries · HTTP handlers depend on DB sessions
- REST routers → Services: delegates · Routers hand off business rules to services
- Services → Domain models: applies · Services operate on the shared domain schema
- Services → Workflow service: includes · Workflow logic coordinates operational automation
- Services → Notifications: includes · Services trigger alerts and reminders
- Chat router → AI agent: calls · Chat endpoint delegates intelligence to the agent layer
- AI agent → DB session: reads · Agent gathers context from application data
- AI agent → Domain models: uses · Agent reasons over domain entities and records
- AI agent → Notifications: may trigger · AI actions can emit operational notifications
- Workflow service → Notifications: triggers · Operational events generate outbound alerts
- Seed data → SQLite DB: populates · Seed script fills the local demo database
- DB session → SQLite DB: persists to · SQLAlchemy sessions store state in SQLite
- REST routers → Chat router: exposes · API layer includes a dedicated chat route
- Chat UI → Chat router: requests · Chat interactions resolve through the chat endpoint