How oussama-sil/sci_api works
Project Type and Purpose
• Type: Backend REST API (monolithic Node.js/Express service)
• Purpose: Expose endpoints for an Intelligent Mailbox system. It accepts hardware (Arduino) events, manages mailbox and person records, dispatches email notifications via SMTP, and persists data in MySQL.
File Structure (Layered Architecture)
Top-level components:
• config/ – configuration (DB credentials, JWT secret)
• index.js – Express app entry point
• routes/ – HTTP route definitions (API layer)
• services/ – business logic (service layer)
• model/ – data access objects (DAO/ORM layer)
• script_database.sql – database schema script
Auxiliary:
• package.json – dependencies (Express, MySQL, JWT, nodemailer)
• .gitignore
• Looping1.lo1, .loo – domain-specific files (can be omitted if not relevant)
README Insights
• Confirms tech stack: Node.js/Express, MySQL
• Core functionality: Intelligent mailbox API (CRUD for persons/mailboxes, event ingestion, email notifications)
Main Components
A. External Clients/Systems
• Arduino device (sends events via HTTP POST)
• Administrator/Client application or CLI (consumes API, e.g., user management)
• SMTP Email Service (third-party or in-house mail server)
B. API Server (Node.js/Express)
1. API Gateway Layer
• index.js (Express app)
• Routes (routes/*.js)
2. Service Layer
• services/*.js – contains business logic, orchestrates data access and external calls (e.g., mailer.js uses nodemailer)
3. Data Access Layer
• model/*.js – interacts with MySQL via queries or ORM
4. Configuration
• config/database_config.js
• config/jwt_secret.js
C. Persistence
• MySQL Database (tables for persons, mailboxes, events, assignments)
Relationships and Interactions
• Arduino → HTTP POST → /routes/arduino.js → services/event.js → model/event.js → MySQL
• Admin UI/CLI → HTTP REST → other routes (person, mailbox, assign) → respective services → models → MySQL
• On certain events, services/mailer.js → SMTP Service (via nodemailer) → End-user email inbox
• Authentication: services/login.js uses JWT secret to issue tokens → routes protected by token verification
Architectural Patterns & Design Principles
• Layered (Controller/Route → Service → Data Access)
• Single monolithic deployable service
• Separation of concerns: routing vs. business logic vs. persistence
• Config-driven credentials and secrets
• Top layer: Routes (list route files)
• Middle layer: Services (list key services)
• Bottom layer: Models (list key models)
• Sidebar: Config modules (DB, JWT)
• Arduino → Routes/arduino.js → services/event.js
• Admin Client → all other Routes → corresponding Services
• Services/mailer.js → SMTP Server
• Models → MySQL
5) Special flows, e.g., JWT authentication flow at login.