Sign inSign up

atharvakote/chemcloud-backend

By atharvakote

Updated 4 months ago

API server for ChemCloud Web Service

Image
API management
Web servers
Databases & storage
1

450

atharvakote/chemcloud-backend repository overview

ChemCloud

Images

Chemical inventory management system with real-time stock tracking, user authentication, and comprehensive reporting.


Overview

ChemCloud is a full-stack chemical inventory management system designed for educational institutions and laboratories. It provides secure authentication, stock movement tracking, year-based reporting, real-time updates, and exportable reports, all optimized for performance and scalability.


Table of Contents

  1. Overview
  2. Features
  3. System Architecture
  4. Tech Stack
  5. Quick Start
  6. Project Structure
  7. API Endpoints
  8. Environment Variables
  9. Security Features
  10. Database Models
  11. Deployment
  12. Monitoring
  13. Troubleshooting
  14. Contributing
  15. Roadmap
  16. Author

1. Key Features

Core Functionality

FeatureDescription
Faculty AuthenticationSecure login/signup using JWT + HttpOnly cookies
Chemical Master DBAdd/update chemicals with measuring units & pack sizes
Stock TrackingLog purchases & usage with auto-year handling
Real-time SearchInstant chemical search powered by Socket.IO
ReportsYear-wise reports, balance sheets, usage logs
ExportsDownload PDF / XLSX reports
Responsive UIFully responsive React/Tailwind interface

Advanced System Capabilities

CapabilityDescription
Multi-instance scalingRedis-powered communication + rate limiting
Distributed Rate LimitingProtects API using Redis tokens
MonitoringHealth endpoints + structured logs
Dockerized InfrastructureFull Docker + Compose support
Graceful ShutdownSafe cleanup and connection closure
LoggingWinston-based structured logs

2. System Architecture

High-Level Architecture (Mermaid Diagram)

flowchart LR
  A[React Frontend] -- Axios/Socket.IO --> B[Express API]
  B -- Mongo Queries --> C[(MongoDB)]
  B -- Cache/Rate Limit --> D[(Redis)]
  A -- Static Assets --> E[Nginx]
  subgraph Container Stack
      B
      E
  end

Request Flow Overview

sequenceDiagram
    participant F as Faculty (User)
    participant FE as Frontend
    participant API as Express API
    participant DB as MongoDB
    participant R as Redis

    F->>FE: Login request
    FE->>API: POST /login
    API->>DB: Verify credentials
    API->>FE: JWT Cookie (HttpOnly)

    F->>FE: Search Chemical
    FE->>API: GET /chemical?q=...
    API->>R: Cache/Ratelimit
    API->>DB: Fetch Chemicals
    API->>FE: Results
    API->>FE: Socket.IO update events

3. Tech Stack

Backend

TechPurpose
Node.js 20Runtime
Express.js 5API framework
MongoDB 7Primary database
Redis 7Cache + rate limiting
JWT + BcryptAuthentication & hashing
HelmetSecurity headers
WinstonLogging
Socket.IOReal-time updates

Frontend

TechPurpose
React 18UI framework
ViteBundler
TailwindCSSStyling
Shadcn/UIComponents
AxiosAPI requests
Socket.IO ClientReal-time
jsPDF / XLSXDocument exports

DevOps

ToolUse
DockerContainerization
Docker ComposeMulti-container orchestration
NginxProduction frontend hosting
GitHub ActionsCI/CD

4. Quick Start

git clone https://github.com/Atharvkote/ChemCloud.git
cd ChemCloud

cp .env.example .env
docker-compose up -d

Access:(Local)

View logs:

docker-compose logs -f

Local Development

Backend
cd server
npm install
npm run dev
Frontend
cd client
npm install
npm run dev

5. Project Structure

server/
 ├── configs/
 ├── controllers/
 ├── models/
 ├── routes/
 ├── middlewares/
 ├── socket-handlers/
 ├── utils/
 ├── Dockerfile
 └── server.js

client/
 ├── src/
 │   ├── components/
 │   ├── pages/
 │   ├── contexts/
 │   ├── hooks/
 │   ├── services/
 │   └── App.jsx
 ├── Dockerfile
 ├── nginx.conf
 └── vite.config.js

6. API Endpoints

Authentication

MethodEndpointDescription
POST/signupCreate account
POST/loginLogin
POST/logoutLogout
GET/check-authValidate token

Chemicals

MethodEndpoint
GET/chemical
GET/chemical/:id
POST/chemical
PUT/chemical/:id
DELETE/chemical/:id

Chemical Records

MethodEndpoint
GET/chemical-report
GET/chemical-report/balance/:id
POST/chemical-report
DELETE/chemical-report/:id

7. Environment Variables

KeyDescription
MONGODB_URIMongo connection
REDIS_URLRedis instance
JWT_SECRETToken signing secret
SERVER_PORTAPI port
CORS_ORIGINAllowed origins

Refer: .env.example


8. Security Features

Security LayerDetails
HttpOnly JWTProtects against XSS
Bcrypt HashingSecure passwords
Helmet HeadersIndustry-standard headers
Rate Limiting100 req / 30 seconds
SanitizationInput cleaning
Docker Non-root UserEnhanced safety

9. Database Models

ER Diagram

erDiagram
    FACULTY ||--o{ CHEMICAL : created_by
    FACULTY ||--o{ CHEMICAL_RECORD : updated_by
    CHEMICAL ||--o{ CHEMICAL_RECORD : has

    FACULTY {
        string name
        string email
        string mobile
    }

    CHEMICAL {
        string name
        string baseUnit
        number primaryPackSize
    }

    CHEMICAL_RECORD {
        int year
        string entryType
        number usedQty
        number openingQty
        number closingQty
    }

10. Deployment

Build Images
docker build -t chemcloud-api ./server
docker build -t chemcloud-frontend ./client
Start
docker-compose up -d

11. Monitoring

ToolUsage
/healthCheck API status
Docker Logsdocker-compose logs -f
Browser DevToolsUI/Socket debugging
Winston LogsServer runtime logs

12. Troubleshooting

IssueFix
MongoDB connection errorCheck URI / Mongo running
Redis not connectingDisable Redis for local mode
CORS errorAdd correct domain to CORS_ORIGIN
Socket.IO failCheck network & server console
JWT invalidLogout → Login again

13. Roadmap

VersionPlanned Features
v1.1Unit tests, categories, rich reporting
v1.2Mobile app, equipment tracking
v2.0Multi-institution, analytics dashboard, ML predictions

14. Author

Atharv Kote – Full Stack Developer

Tag summary

Content type

Image

Digest

sha256:4e57c06ae

Size

53.4 MB

Last updated

4 months ago

docker pull atharvakote/chemcloud-backend