https://github.com/codewizard-404/traceflow
TraceFlow is an AI-powered platform for Enda Tao, streamlining territorial activity tracking, timesheet management, and receipt book traceability. With secure authentication, geolocation, real-time notifications, and AI-driven analytics, it empowers roles like Supervisors, Regional Managers, and HR with dynamic dashboards and multilingual support.
https://github.com/codewizard-404/traceflow
flutter google-cloud-platform keycloak nginx nodejs pm2 postgresql react-tsx redis websocket
Last synced: 5 months ago
JSON representation
TraceFlow is an AI-powered platform for Enda Tao, streamlining territorial activity tracking, timesheet management, and receipt book traceability. With secure authentication, geolocation, real-time notifications, and AI-driven analytics, it empowers roles like Supervisors, Regional Managers, and HR with dynamic dashboards and multilingual support.
- Host: GitHub
- URL: https://github.com/codewizard-404/traceflow
- Owner: CodeWizard-404
- Created: 2025-02-05T14:43:06.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-04T19:28:21.000Z (7 months ago)
- Last Synced: 2025-09-04T21:25:43.723Z (7 months ago)
- Topics: flutter, google-cloud-platform, keycloak, nginx, nodejs, pm2, postgresql, react-tsx, redis, websocket
- Language: TypeScript
- Homepage:
- Size: 171 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 227
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🌟 TraceFlow: AI-Powered Efficiency for Enda Tao 🚀
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://flutter.dev/)
[](https://www.postgresql.org/)
[](https://www.docker.com/)
**TraceFlow** is a state-of-the-art, AI-driven platform developed for **Enda Tao** to streamline territorial activity tracking, timesheet management, and receipt book traceability. Created as a final-year project, TraceFlow empowers roles such as Super Admin, Admin, Director, Regional Manager, Supervisor, Purchase Team, Stock Manager, and HR with secure authentication, geolocation, real-time updates, and AI-powered analytics. Featuring dynamic dashboards, multilingual support (English, French, Arabic), and seamless integrations, TraceFlow delivers operational excellence in a scalable, user-centric package. 🌍
---
## 📑 Table of Contents
- [🌟 Overview](#-overview)
- [🔥 Key Features](#-key-features)
- [🏗️ System Architecture](#-system-architecture)
- [🛠️ Technology Stack](#-technology-stack)
- [🚀 Getting Started](#-getting-started)
- [⚙️ Configuration](#-configuration)
- [🎮 Usage](#-usage)
- [📚 API Documentation](#-api-documentation)
- [🧪 Testing](#-testing)
- [🚀 Deployment](#-deployment)
- [🤝 Contributing](#-contributing)
- [📜 License](#-license)
- [📬 Support](#-support)
---
## 🌟 Overview
TraceFlow revolutionizes Enda Tao’s operational workflows by digitizing and optimizing key processes. It integrates:
- **Timesheet Management**: Streamlined creation, validation, and AI-driven scheduling. 📅
- **Visit Tracking**: Real-time geolocation and QR code-based logging. 📍
- **Receipt Book Traceability**: Secure tracking with QR codes and OTP. 📚
- **AI Analytics**: Anomaly detection and actionable insights. 🤖
- **Dynamic Dashboards**: Role-specific, multilingual interfaces. 📊
- **Real-Time Notifications**: WebSocket-driven alerts for instant updates. 🔔
Built for scalability and security, TraceFlow leverages modern technologies to ensure efficiency, traceability, and accountability.
---
## 🔥 Key Features
- **Timesheet Management** 📅
- Create, edit, validate, and delete timesheets with role-based access.
- AI-generated suggestions (up to 5 per request) for optimized scheduling.
- Filter by week, year, or role (e.g., Supervisor, HR).
- **Visit Tracking** 📍
- Log visits via QR code scanning and OTP validation.
- Google Maps integration for real-time agent tracking, route optimization, and nearby agent detection.
- Filter by regions, governorates, or delegations.
- **Receipt Book Traceability** 📚
- Secure tracking with QR codes and OTP for books and stubs.
- Transfer history, stock management, and validation for Purchase Team and Stock Manager roles.
- Comprehensive audit trails.
- **AI-Powered Analytics** 🤖
- Anomaly detection with a 0.95 confidence threshold.
- Automated report generation for Directors and Admins.
- **Dynamic Dashboards** 📊
- Interactive, role-specific KPIs with dark mode support.
- Multilingual: English, French, Arabic.
- **Real-Time Notifications** 🔔
- WebSocket-based alerts for timesheet approvals, visit logs, and receipt transfers.
- Configurable notification rules.
- **Secure Authentication** 🔒
- Keycloak with OAuth2 and Google Auth integration.
- Token lifespans: Access (15 min), Refresh (1 day), SSO Session (1 day, idle: 9 hours).
- **Rate Limiting** ⚡
- Sensitive operations: 10 requests/10 min.
- OTP and refresh token limits for security.
- **Logging** 📜
- 30-day retention with log statistics, filters, and health metrics.
- Max page size: 500, default: 50.
> **Tip**: TraceFlow supports up to 5 file downloads per session for reports and logs.
---
## 🏗️ System Architecture
TraceFlow’s modular architecture ensures scalability and maintainability:
- **Frontend (Web)**: React with TypeScript, Vite, and Tailwind CSS for responsive dashboards.
- **Frontend (Mobile)**: Flutter for cross-platform Android/iOS apps.
- **Backend**: Node.js with Express.js for API, authentication, and WebSocket communication.
- **Database**: PostgreSQL for relational data, Redis for caching.
- **AI Engine**: Ollama with Mistral model for analytics and suggestions.
- **Authentication**: Keycloak for SSO, Google OAuth2 for Maps and Calendar.
- **Infrastructure**: Docker for containerization, NGINX for reverse proxy, PM2 for process management.
📊 Architecture Diagram
---
## 🛠️ Technology Stack
TraceFlow leverages a modern, robust tech stack, showcased with GitHub-style badges for clarity and visual appeal:
| **Category** | **Technologies** |
|-------------------------|---------------------------------------------------------------------------------|
| **Frontend (Web)** | [](https://reactjs.org/) [](https://www.typescriptlang.org/) [](https://vitejs.dev/) [](https://tailwindcss.com/) |
| **Frontend (Mobile)** | [](https://flutter.dev/) [](https://dart.dev/) |
| **Backend** | [](https://nodejs.org/) [](https://expressjs.com/) |
| **Database** | [](https://www.postgresql.org/) [](https://redis.io/) |
| **Authentication** | [](https://www.keycloak.org/) [](https://developers.google.com/identity) |
| **AI Engine** | [](https://ollama.ai/) |
| **Real-Time** | [](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) |
| **API Docs** | [](https://swagger.io/) |
| **Testing** | [](https://jestjs.io/) [](https://www.postman.com/) [](https://flutter.dev/docs/testing) |
| **Infrastructure** | [](https://www.docker.com/) [](https://nginx.org/) [](https://pm2.keymetrics.io/) |
| **External Services** | [](https://developers.google.com/maps) [](https://developers.google.com/calendar) [](https://wbm.tn/) [](https://support.google.com/mail) |
| **Logging** | Custom logger (30-day retention, log filters, metrics) |
| **CSV Processing** | UTF-8 (fallback: win1252), comma-delimited, JSON config |
---
## 🚀 Getting Started
### Prerequisites
- [](https://nodejs.org/) Node.js v22.14 or later
- [](https://www.postgresql.org/) PostgreSQL with pgAdmin4 v9
- [](https://redis.io/) Redis (latest stable)
- [](https://www.docker.com/) Docker for Keycloak and Redis
- [](https://flutter.dev/) Flutter v3.29, Dart 3.7
- [](https://git-scm.com/) Git for repository access
### Installation
1. **Clone the Repository**:
```bash
git clone https://github.com/CodeWizard-404/traceflow.git
cd traceflow
```
2. **Install Backend Dependencies**:
```bash
cd Back
npm install
```
3. **Install Frontend (Web) Dependencies**:
```bash
cd ../Front
npm install
```
4. **Install Mobile Dependencies**:
```bash
cd ../Mobile
flutter pub get
```
5. **Set Up Database**:
- Create a PostgreSQL database: `traceflow_db`.
- Run migrations:
```bash
cd Back
npm run migrate
```
6. **Start Docker Containers**:
- Launch Keycloak and Redis:
```bash
docker-compose up -d
```
---
## ⚙️ Configuration
Configuration is managed via `.env` files included in the repository. Key settings are detailed below:
### Backend `.env`
🔍 View Backend Configuration
- **Database**:
- Host: `localhost:5432`
- User: `postgres`
- Password: `admin`
- Database: `traceflow_db`
- **URLs**:
- Development: `http://localhost`
- Production: `https://localhost`
- Frontend: `http://localhost:5173`, `http://192.168.1.21:5173`, `http://192.168.1.100`
- Login: `http://localhost:5173/login`
- Redirect: `http://localhost:5000/api/auth/callback`
- **Keycloak**:
- URL: `http://localhost:8080`
- Realm: `TraceFlow`
- Client ID: `traceflow-backend`
- Client Secret: `9FQJDVvEU3MZvB9CGxuM50IcTVOapED7`
- Admin: Configured for administrative access
- **Google APIs**:
- Maps API Key: `AIzaSyDkbpHSSJc-fsV5fcwYkSxk0Mq0RNCAb7g`
- Calendar Client ID: `803294683158-1o22qb2cda9c5mgvj5dhn8pdcn11jo45.apps.googleusercontent.com`
- Calendar Redirect URI: `http://localhost:5000/api/auth/google-calendar-auth/callback`
- **Redis**:
- Host: `localhost:6379`
- Cluster: Disabled
- **Ollama (AI)**:
- URL: `http://localhost:11434/api`
- Model: `mistral`
- Timeout: 5 minutes
- Max Retries: 3
- Anomaly Threshold: 0.95
- Max Timesheet Suggestions: 5
- **SMTP**:
- Host: `smtp.gmail.com:587`
- Configured with app-specific credentials
- **SMS**:
- WBM.tn API (v5): `https://wbm.tn/wbmonitor/send/webapi/v5/`
- API Key: `9c5362a406e609d0ecc6f9a0e129c0a6`
- WBM.tn API (v3): `https://wbm.tn/wbmonitor/send/webapi/v3/send_ack.php`
- Username: `enda-cash`
- Password: Configured for secure access
- **Rate Limiting**:
- Sensitive Operations: 10 requests/10 min
- OTP: 10 requests/10 min
- Refresh Tokens: 5 requests/10 min
- **Logging**:
- Level: `info`
- Retention: 30 days
- Secret: Configured for secure logging
- Sample Rate: 1
- **CSV Processing**:
- Encoding: `utf8` (fallback: `win1252`)
- Delimiter: `,`
- Config Path: `./config/csv-config.json`
- **Roles**:
- Super Admin, Admin, Director, Regional Manager, Supervisor, Purchase Team, Stock Manager, HR
- **Initialization**:
- Enabled: Database, SMTP, SMS, Redis, Google Services, WebSocket, etc.
- **Vault**:
- Address: `http://127.0.0.1:8200`
- Token: Configured for secret management
- **mDNS**: Enabled for local discovery
### Frontend `.env`
🔍 View Frontend Configuration
- **API**:
- URL: `http://192.168.1.21:5000/api`
- Timeout: 30 seconds
- Access Token Lifespan: 15 minutes
- **Keycloak**: Matches backend configuration
- **Google APIs**: Configured for Maps and Calendar
- **Permissions** (Selected):
- **Users**: `access_all_users`, `create_users`, `update_users`, `delete_users`
- **Timesheets**: `access_all_timesheets`, `validate_timesheets`, `suggest_timesheets`
- **Visits**: `scan_visits`, `log_visits`, `sync_calendar`
- **Receipt Books**: `transfer_receipt_books`, `validate_receipt_stubs`, `access_receipt_book_history`
- **Agents**: `access_agents_by_location`, `update_agents_location`, `access_nearby_agents`
- **Notifications**: `trigger_notifications`, `manage_notification_rules`
- **Logs**: `view_logs`, `archive_logs`, `export_logs`, `view_logger_metrics`
- **Reports**: `generate_report`, `schedule_report`, `download_report`
- **AI**: `access_ai_anomaly_detection`, `manage_ai_config`
- **Roles**: Matches backend roles
- **Checklist Items**:
- `Transfer a receipt book`
- `Collect receipt stub`
### Mobile Configuration
🔍 View Mobile Configuration
- **Base URL**: `http://192.168.1.21:5000/api`
- **Keycloak**:
- URL: `http://localhost:8080`
- Realm: `TraceFlow`
- Client ID: `traceflow-backend`
- Client Secret: `9FQJDVvEU3MZvB9CGxuM50IcTVOapED7`
- Redirect URI: `http://localhost:8080/realms/TraceFlow/broker/google/endpoint`
- **Google**:
- Web Client ID: `803294683158-1o22qb2cda9c5mgvj5dhn8pdcn11jo45.apps.googleusercontent.com`
- Android Client ID: `803294683158-jf323a7qjjo3nfblgl2nao9il1fgroia.apps.googleusercontent.com`
- iOS Client ID: `803294683158-47b4jojal7je374cr7n4qh7ra47pcttq.apps.googleusercontent.com`
### Additional Setup
- **Keycloak**:
- Admin Console: `http://localhost:8080`
- Configure `TraceFlow` realm, clients, and roles.
- **Google APIs**:
- Enable Maps and Calendar APIs in Google Cloud Console.
- Update `.env` files with credentials.
- **SSL (Production)**:
- Paths: `/etc/ssl/private/key.pem`, `/etc/ssl/certs/cert.pem`
- **Vault**:
- Address: `http://127.0.0.1:8200`
- Token: Configured for secure secrets.
---
## 🎮 Usage
- **Web Application**:
- Start backend:
```bash
cd Back
npm start
```
- Start frontend:
```bash
cd ../Front
npm run dev
```
- Access: `http://localhost:5173`
- **Mobile Application**:
- Run Flutter app:
```bash
cd Mobile
flutter run
```
### Example Workflows
- **Log a Visit** 📍:
- Scan QR code, enter OTP, complete checklist (e.g., “Transfer a receipt book”).
- View agent locations on Google Maps.
- **Manage Timesheets** 📅:
- Create timesheets, review AI suggestions, and validate via web interface.
- Filter by week, year, or role.
- **Track Receipt Books** 📚:
- Scan QR codes to transfer books or collect stubs.
- Validate transfers or view history.
- **Generate Reports** 📊:
- Schedule AI-driven reports or download (max 5 per session).
- Analyze anomalies (0.95 threshold).
---
## 📚 API Documentation
- Access Swagger docs: `http://localhost:5000/api-docs`
- Key Endpoints:
- **Users**: `/api/users`, `/api/roles/assign`, `/api/users/by-role`
- **Timesheets**: `/api/timesheets`, `/api/timesheets/suggest`, `/api/timesheets/validate`
- **Visits**: `/api/visits`, `/api/visits/scan`, `/api/visits/sync-calendar`
- **Receipt Books**: `/api/receipt-books`, `/api/receipt-books/transfer`, `/api/receipt-books/history`
- **Agents**: `/api/agents`, `/api/agents/locations`, `/api/agents/nearby`
- **Notifications**: `/api/notifications`, `/api/notifications/rules`
- **Logs**: `/api/logs`, `/api/logs/export`, `/api/logs/statistics`
- **Reports**: `/api/reports/generate`, `/api/reports/schedule`
---
## 🧪 Testing
- **Unit Tests**:
- Backend:
```bash
cd Back
npm test
```
- Mobile:
```bash
cd Mobile
flutter test
```
- **API Tests**:
- Use Postman collections in `Back/tests`.
- **Coverage**:
- Target 80%+ coverage for critical modules.
---
## 🚀 Deployment
- **Development**:
- Set `NODE_ENV=development`.
- Start services:
```bash
docker-compose up -d
```
- **Production**:
- Set `NODE_ENV=production` and update `PROD_URL`.
- Configure NGINX:
```bash
nginx -s reload
```
- Manage Node.js with PM2:
```bash
pm2 start Back/app.js --name traceflow-backend
```
- Deploy with Docker:
```bash
docker-compose -f docker-compose.prod.yml up -d
```
- Enable HTTPS with SSL certificates.
---
## 🤝 Contributing
Contributions are welcome to enhance TraceFlow’s capabilities.
- **Issues**: Report bugs or suggest features via [GitHub Issues](https://github.com/CodeWizard-404/traceflow/issues).
- **Pull Requests**:
- Fork the repository.
- Create a branch: `git checkout -b feature/your-feature`.
- Commit changes and submit a pull request.
- **Guidelines**:
- Follow ESLint, TypeScript, and Dart standards.
- Include unit tests.
- Provide detailed PR descriptions.
---
## 📜 License
[](https://opensource.org/licenses/MIT)
---
## 📬 Support
For inquiries or issues, please use [GitHub Issues](https://github.com/CodeWizard-404/traceflow/issues). Additional support is available through the platform’s official channels.
---
**TraceFlow** – Empowering Enda Tao with AI-driven efficiency, traceability, and scalability. 🌍