# eltacher/yzta-5.0_ai_hackathon architecture

> Architecture diagram of the GitHub repository eltacher/yzta-5.0_ai_hackathon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eltacher/yzta-5.0_ai_hackathon
- Repository: https://github.com/eltacher/yzta-5.0_ai_hackathon

## Overview

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: [`frontend/js/app.js`](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/app.js) (App shell), [`backend/routers`](https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/routers) (REST routers), [`backend/services`](https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/services) (Services), [`frontend/js/api.js`](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_frontend_app["App shell<br/>SPA bootstrap<br/>[app.js]"]
  node_frontend_api["API client<br/>HTTP client<br/>[api.js]"]
  node_frontend_components["UI components<br/>shared UI<br/>[components.js]"]
  node_frontend_dashboard["Dashboard<br/>feature view<br/>[dashboard.js]"]
  node_frontend_orders["Orders UI<br/>feature view<br/>[orders.js]"]
  node_frontend_inventory["Inventory UI<br/>feature view<br/>[inventory.js]"]
  node_frontend_chat["Chat UI<br/>feature view<br/>[chat.js]"]
end

subgraph group_backend["FastAPI Backend"]
  node_backend_main["App entry<br/>FastAPI app<br/>[main.py]"]
  node_backend_db["DB session<br/>SQLAlchemy setup<br/>[database.py]"]
  node_backend_models[("Domain models<br/>ORM schema<br/>[models.py]")]
  node_backend_api["REST routers<br/>API layer"]
  node_backend_services["Services<br/>business logic"]
  node_backend_ai_chat["Chat router<br/>API endpoint<br/>[ai_chat.py]"]
  node_backend_workflow["Workflow service<br/>automation logic"]
  node_backend_notify["Notifications<br/>side effects"]
end

subgraph group_data["Data Layer"]
  node_backend_seed["Seed data<br/>initializer<br/>[seed_data.py]"]
  node_backend_sqlite[("SQLite DB<br/>persistent store<br/>[yzta_ecommerce.db]")]
end

subgraph group_ai["AI Integration"]
  node_backend_ai_agent["AI agent<br/>Gemini orchestration<br/>[ai_agent.py]"]
end

node_frontend_app -->|"uses"| node_frontend_api
node_frontend_app -->|"composes"| node_frontend_components
node_frontend_app -->|"loads"| node_frontend_dashboard
node_frontend_app -->|"loads"| node_frontend_orders
node_frontend_app -->|"loads"| node_frontend_inventory
node_frontend_app -->|"loads"| node_frontend_chat
node_frontend_dashboard -->|"fetches"| node_frontend_api
node_frontend_orders -->|"fetches"| node_frontend_api
node_frontend_inventory -->|"fetches"| node_frontend_api
node_frontend_chat -->|"sends"| node_frontend_api
node_backend_main -->|"mounts"| node_backend_api
node_backend_main -->|"configures"| node_backend_db
node_backend_main -->|"orchestrates"| node_backend_services
node_backend_api -->|"uses"| node_backend_models
node_backend_api -->|"queries"| node_backend_db
node_backend_api -->|"delegates"| node_backend_services
node_backend_services -->|"applies"| node_backend_models
node_backend_services -->|"includes"| node_backend_workflow
node_backend_services -->|"includes"| node_backend_notify
node_backend_ai_chat -->|"calls"| node_backend_ai_agent
node_backend_ai_agent -->|"reads"| node_backend_db
node_backend_ai_agent -->|"uses"| node_backend_models
node_backend_ai_agent -.->|"may trigger"| node_backend_notify
node_backend_workflow -->|"triggers"| node_backend_notify
node_backend_seed -->|"populates"| node_backend_sqlite
node_backend_db -->|"persists to"| node_backend_sqlite
node_backend_api -->|"exposes"| node_backend_ai_chat
node_frontend_chat -->|"requests"| node_backend_ai_chat

click node_frontend_app "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/app.js"
click node_frontend_api "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/api.js"
click node_frontend_components "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/components.js"
click node_frontend_dashboard "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/dashboard.js"
click node_frontend_orders "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/orders.js"
click node_frontend_inventory "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/inventory.js"
click node_frontend_chat "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/chat.js"
click node_backend_main "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/main.py"
click node_backend_db "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/database.py"
click node_backend_models "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/models.py"
click node_backend_api "https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/routers"
click node_backend_services "https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/services"
click node_backend_ai_agent "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/ai_agent.py"
click node_backend_ai_chat "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/routers/ai_chat.py"
click node_backend_workflow "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/workflow_service.py"
click node_backend_notify "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/notification_service.py"
click node_backend_seed "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/seed_data.py"
click node_backend_sqlite "https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/yzta_ecommerce.db"

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_frontend_app,node_frontend_api,node_frontend_components,node_frontend_dashboard,node_frontend_orders,node_frontend_inventory,node_frontend_chat toneBlue
class node_backend_main,node_backend_db,node_backend_models,node_backend_api,node_backend_services,node_backend_ai_chat,node_backend_workflow,node_backend_notify toneAmber
class node_backend_seed,node_backend_sqlite toneMint
class node_backend_ai_agent toneRose
```

## Components

### Frontend SPA

Browser-side interface and feature modules

- [App shell](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/app.js): SPA bootstrap · Initializes the browser app and coordinates feature modules · `frontend/js/app.js`
- [API client](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/api.js): HTTP client · Centralizes calls from the SPA to backend endpoints · `frontend/js/api.js`
- [UI components](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/components.js): shared UI · Reusable presentation pieces used across screens · `frontend/js/components.js`
- [Dashboard](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/dashboard.js): feature view · Operational overview and summary screens · `frontend/js/dashboard.js`
- [Orders UI](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/orders.js): feature view · Order management screens and actions · `frontend/js/orders.js`
- [Inventory UI](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/inventory.js): feature view · Stock and inventory management screens · `frontend/js/inventory.js`
- [Chat UI](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/frontend/js/chat.js): feature view · Natural-language interaction surface for AI-assisted operations · `frontend/js/chat.js`

### FastAPI Backend

API, orchestration, and server entrypoint

- [App entry](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/main.py): FastAPI app · Wires routers, static serving, and server startup · `backend/main.py`
- [DB session](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/database.py): SQLAlchemy setup · Database connection and session management · `backend/database.py`
- [Domain models](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/models.py): ORM schema · Products, orders, customers, cargo, inventory, tasks, and analytics records · `backend/models.py`
- [REST routers](https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/routers): API layer · Domain-specific HTTP endpoints for business operations · `backend/routers`
- [Services](https://github.com/eltacher/yzta-5.0_ai_hackathon/tree/main/backend/services): business logic · Cross-route rules, workflows, and notifications · `backend/services`
- [Chat router](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/routers/ai_chat.py): API endpoint · Backend entrypoint for AI chat requests · `backend/routers/ai_chat.py`
- [Workflow service](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/workflow_service.py): automation logic · Coordinates operational triggers, task creation, and business flows · `backend/services/workflow_service.py`
- [Notifications](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/notification_service.py): side effects · Emits alerts and operational reminders · `backend/services/notification_service.py`

### Data Layer

SQLite persistence and seeded demo data

- [Seed data](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/seed_data.py): initializer · Loads demo data into the local database · `backend/seed_data.py`
- [SQLite DB](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/yzta_ecommerce.db): persistent store · Self-contained application database · `backend/yzta_ecommerce.db`

### AI Integration

Chat and agent orchestration path

- [AI agent](https://github.com/eltacher/yzta-5.0_ai_hackathon/blob/main/backend/services/ai_agent.py): Gemini orchestration · Interprets chat intent, gathers context, and generates responses · `backend/services/ai_agent.py`

## Connections

- 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