TermFlow Backend

Self-hosted terminal workflow management backend built with Node.js, Express, and MongoDB.

Project Structure

backend/
├── src/
│   ├── config/                        # Configuration layer
│   │   ├── config.js                  # Constants & env config
│   │   └── database.js                # MongoDB connection
│   │
│   ├── controllers/                   # Request handlers
│   │   ├── authController.js
│   │   ├── workflowController.js
│   │   ├── scheduleController.js
│   │   ├── analyticsController.js
│   │   ├── subscriptionController.js
│   │   └── integrationController.js
│   │
│   ├── models/                        # Mongoose schemas
│   │   ├── User.js
│   │   ├── Workflow.js
│   │   ├── Schedule.js
│   │   ├── ExecutionMetrics.js
│   │   ├── Analytics.js
│   │   ├── Subscription.js
│   │   └── Integration.js
│   │
│   ├── services/                      # Business logic & intelligence
│   │   ├── predictionEngine.js        # ML prediction engine
│   │   ├── cronOptimizer.js           # Cron optimization logic
│   │   └── aiInsights.js              # AI-powered recommendations
│   │
│   ├── middleware/                    # Express middleware
│   │   ├── auth.js                    # JWT auth
│   │   └── error.js                   # Global error handler
│   │
│   └── routes/                        # API routes
│       ├── auth.js
│       ├── workflows.js
│       ├── schedules.js
│       ├── analytics.js
│       ├── subscriptions.js
│       └── integrations.js
│
├── server.js                          # Express server entry
├── package.json
├── .env.example
├── README.md
├── PREDICTIVE_SCHEDULING_API.md
├── PREDICTIVE_SCHEDULING_GUIDE.md
└── PREDICTIVE_SCHEDULING_SUMMARY.md

Installation

Prerequisites

• Node.js 16+

• MongoDB 4.4+ (local or cloud)

• npm or yarn

Setup

1. Clone the repository

git  clone <https://github.com/Termflow/termflow-server>

cd  backend

2. Install dependencies

npm  install

3. Configure environment variables

cp  .env.example  .env

Edit .env and add your configuration:

NODE_ENV=development

PORT=5000

MONGODB_URI=mongodb://localhost:27017/termflow

JWT_SECRET=your-super-secret-key-change-in-production

CLIENT_URL=http://localhost:3000

  

# Third-party services (optional)

STRIPE_SECRET_KEY=sk_...

STRIPE_PUBLISHABLE_KEY=pk_...

GITHUB_TOKEN=ghp_...

SLACK_BOT_TOKEN=xoxb_...

DISCORD_BOT_TOKEN=MTk4NjIyNDgzNDU4MTI4ODk2.Clwa7A...

FIGMA_TOKEN=figd_...

NOTION_TOKEN=secret_...

4. Start the server

Development (with auto-reload):

npm  run  dev

Production:

npm  start

Server will run on http://localhost:5000

API Documentation

Authentication

Register

POST  /api/auth/register

Content-Type:  application/json

  

{
	"name":  "John Doe",
	"email":  "john@example.com",
	"password":  "securePassword123"
}

  

# Response: 201

{
	"message":  "User registered successfully",
	"token":  "eyJhbGc...",
	"user":  {
	"_id":  "...",
	"name":  "John Doe",
	"email":  "john@example.com",
	"role":  "user"
}

}

Login

POST  /api/auth/login

Content-Type:  application/json

  

{
	"email":  "john@example.com",
	"password":  "securePassword123"
}

  

# Response: 200

{
	"message":  "Login successful",
	"token":  "eyJhbGc...",
	"user":  {  ...  }
}

Get Profile

GET  /api/auth/profile

Authorization:  Bearer <token>

Update Profile

PATCH  /api/auth/profile

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"name":  "Jane Doe",
	"avatar":  "https://example.com/avatar.jpg"
}

Workflows

Create Workflow

POST  /api/workflows

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
"name":  "Deploy Pipeline",
"description":  "Automated deployment workflow",
"tasks": [
		{
		"id":  "task-1",
		"name":  "Run Tests",
		"type":  "script",
		"config":  {  "script":  "npm test"  },
		"order":  1
		},
		{
		"id":  "task-2",
		"name":  "Deploy",
		"type":  "api",
		"config":  {  "url":  "https://api.example.com/deploy"  },
		"order":  2
		}
],
"tags": ["deployment", "ci-cd"]
}

Get All Workflows

GET  /api/workflows?page=1&limit=10&status=active

Authorization:  Bearer <token>

Get Single Workflow

GET  /api/workflows/:id

Authorization:  Bearer <token>

Update Workflow

PATCH  /api/workflows/:id

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"name":  "Updated Name",
	"status":  "inactive"
}

Delete Workflow

DELETE  /api/workflows/:id

Authorization:  Bearer <token>

Execute Workflow

POST  /api/workflows/:id/execute

Authorization:  Bearer <token>

Schedules

Create Schedule

POST  /api/schedules

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"name":  "Daily Backup",
	"workflowId":  "...",
	"cronExpression":  "0 2 * * *",
	"timezone":  "UTC"
}

Get All Schedules

GET  /api/schedules?page=1&limit=10&workflowId=...

Authorization:  Bearer <token>

Get Single Schedule

GET  /api/schedules/:id

Authorization:  Bearer <token>

Update Schedule

PATCH  /api/schedules/:id

Authorization:  Bearer <token>

Content-Type:  application/json

  

{

"cronExpression":  "0 3 * * *"

}

Toggle Schedule

PATCH  /api/schedules/:id/toggle

Authorization:  Bearer <token>

Get Execution History

GET  /api/schedules/:scheduleId/history?limit=20

Authorization:  Bearer <token>

Delete Schedule

DELETE  /api/schedules/:id

Authorization:  Bearer <token>

Analytics

Get Analytics

GET  /api/analytics?workflowId=...&startDate=2024-01-01&endDate=2024-01-31&limit=100

Authorization:  Bearer <token>

Get Stats

GET  /api/analytics/stats/overview?workflowId=...&days=30

Authorization:  Bearer <token>

  

# Response

{
	"period":  {  "startDate":  "...",  "endDate":  "..."  },
	"executions":  42,
	"successCount":  40,
	"failureCount":  2,
	"successRate":  "95.24",
	"avgDuration":  "1250.50",
	"events":  {  ...  }
}

Get Top Workflows

GET  /api/analytics/workflows/top?limit=10

Authorization:  Bearer <token>

Subscriptions

Get Subscription

GET  /api/subscriptions

Authorization:  Bearer <token>

Create Subscription

POST  /api/subscriptions

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"plan":  "pro",
	"billingCycle":  "monthly"
}

Upgrade Plan

PATCH  /api/subscriptions/upgrade

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"newPlan":  "enterprise"
}

Check Plan Limits

GET  /api/subscriptions/limits/check

Authorization:  Bearer <token>

Cancel Subscription

DELETE  /api/subscriptions/cancel

Authorization:  Bearer <token>

Integrations

Connect Integration

POST  /api/integrations

Authorization:  Bearer <token>

Content-Type:  application/json

  

{
	"provider":  "github",
	"accessToken":  "ghp_...",
	"metadata":  {  "username":  "john"  }
}

Get All Integrations

GET  /api/integrations?isActive=true

Authorization:  Bearer <token>

Get Single Integration

GET  /api/integrations/:provider

Authorization:  Bearer <token>

Toggle Integration

PATCH  /api/integrations/:provider/toggle

Authorization:  Bearer <token>

Test Integration

POST  /api/integrations/:provider/test

Authorization:  Bearer <token>

Disconnect Integration

DELETE  /api/integrations/:provider

Authorization:  Bearer <token>

Available Plans

Free

• 5 workflows

• 10 schedules

• 2 integrations

• 30-day analytics retention

Pro

• 50 workflows

• 100 schedules

• 10 integrations

• 365-day analytics retention

• API access

Enterprise

• Unlimited workflows

• Unlimited schedules

• Unlimited integrations

• 999-day analytics retention

• API access

• Custom branding

Cron Expression Examples

0 * * * * Every hour

0 0 * * * Daily at midnight

0 0 * * 0 Weekly on Sunday

0 0 1 * * Monthly on 1st

0 0 1 1 * Yearly on Jan 1

*/5 * * * * Every 5 minutes

0 9-17 * * * Every hour 9am-5pm

Database Models

User

• name - Full name

• email - Email address (unique)

• password - Hashed password

• role - user, admin, or team-lead

• subscription - Reference to Subscription

• integrations - Array of Integration references

• lastLogin - Last login timestamp

• isActive - Account status

Workflow

• name - Workflow name

• description - Description

• userId - Owner user ID

• tasks - Array of task configurations

• status - active, inactive, or archived

• isPublic - Public visibility

• executions - Execution stats

• tags - Workflow tags

Schedule

• name - Schedule name

• workflowId - Reference to Workflow

• userId - Owner user ID

• cronExpression - Cron schedule

• timezone - Timezone

• isActive - Active status

• executionHistory - Array of past executions

Analytics

• userId - User ID

• workflowId - Workflow ID (optional)

• scheduleId - Schedule ID (optional)

• event - Event type

• duration - Execution duration

• status - Status

• timestamp - Event timestamp

Subscription

• userId - User ID

• plan - free, pro, or enterprise

• status - active, canceled, or expired

• stripeCustomerId - Stripe customer ID

• stripeSubscriptionId - Stripe subscription ID

• features - Plan features

• billingCycle - monthly or yearly

• currentPeriodStart - Period start

• currentPeriodEnd - Period end

Integration

• userId - User ID

• provider - Service provider

• accessToken - Auth token

• refreshToken - Refresh token (optional)

• metadata - Provider-specific data

• isActive - Connection status

Security Features

• Password hashing with bcryptjs

• JWT-based authentication

• Role-based access control

• Environment variable management

• CORS configuration

• Input validation

• Error handling middleware

Error Handling

All endpoints return consistent error responses:

{

"error": "Error message"

}

HTTP Status Codes:

• 200 - OK

• 201 - Created

• 400 - Bad Request

• 401 - Unauthorized

• 403 - Forbidden

• 404 - Not Found

• 500 - Server Error

Deployment

Docker

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 5000

CMD ["npm", "start"]

Environment Setup

For production:

1. Use a strong JWT_SECRET

2. Set NODE_ENV=production

3. Configure MongoDB Atlas or similar

4. Use environment-specific credentials

5. Enable HTTPS

6. Configure CORS for frontend domain

7. Set up monitoring and logging

Database Backups

MongoDB provides built-in backup solutions:

• Use MongoDB Atlas automated backups

• Or set up mongodump/mongorestore cron jobs

Contributing

1. Create a feature branch

2. Make your changes

3. Test thoroughly

4. Submit a pull request

License

MIT