RISTEK Link

📖 Table of Contents

• 🔗 RISTEK Link Documentation
  • 📖 Table of Contents
  • 1. Introduction
  • 2. Core Technologies
  • 3. Project Setup
  • 4. 🔐 Environment Variables
    • a. Backend Environment Variables
    • b. Frontend Environment Variables
  • 5. 📁 Folder Structure
    • a. Backend Folder Structure
    • b. Frontend Folder Structure
  • 7. 🌐 API Endpoints
  • 8. 📊 Diagrams
    • Database Schema
    • URL Shortening Flow
    • Authentication Flow
    • URL Redirection Flow
    • Analytics Flow
    • Domain Management Flow
  • 9. 🔧 Development Notes

1. Introduction

RISTEK Link is a modern URL shortener and link management platform built for RISTEK Universitas Indonesia. This documentation provides a comprehensive technical overview of both frontend and backend implementations, including architecture, core technologies, and key features.

2. Core Technologies

Backend Technologies

• Framework: Express.js
• Language: TypeScript
• Database: FireStore
• Authentication: Standard Auth and Google OAuth
• Logging: Winston
• Mailer Service: Sendinblue
• Analytics: Mixpanel
• Error Tracking: Sentry
• Risk Mitigation: Google Web Risk API

Frontend Technologies

• Framework: Next.js 12 (using App Router)
• UI Libraries:
  • Chakra UI
  • TailwindCSS
  • Material UI
  • Framer Motion
• Authentication: Google OAuth
• Analytics:
  • Mixpanel
  • Chart.js
• Monitoring: Sentry
• Other Libraries:
  • Axios for API requests
  • AWS SDK for cloud services
  • QR Code generation
  • JWT for token management

3. Project Setup

(Details about local development setup, build commands, etc., would typically go here. Assuming standard Next.js setup.)

1. Clone the repository.
2. Install dependencies:

npm install
# or
yarn install

3. Set up environment variables: Create a .env.local file based on .env.example (if available) or the Environment Variables section.
4. Run the development server:

npm run dev
# or
yarn dev

5. Build for production:

npm run build
# or
yarn build

---

4. 🔐 Environment Variables

The application relies on several environment variables for its configuration. These should be defined in a .env.local file in the project root.

a. Backend Environment Variables

Variable Name	Description	Expected Format	Example
PORT	Port number on which the backend server runs.	Integer	5000
JWT_SECRET	Secret key used for signing and verifying JWTs.	Arbitrary string	<INSERT_JWT_SECRET_HERE>
NODE_ENV	Node environment (development or production).	development | production	development
SENDINBLUE_API_KEY	API key for Sendinblue email service.	String	<INSERT_SENDINBLUE_API_KEY_HERE>
CLIENT_HOST	URL for the client-side reset password page with token parameter.	URL string	http://localhost:3000/login/reset?token=

b. Frontend Environment Variables

Variable Name	Description	Expected Format	Example
NEXT_PUBLIC_GOOGLE_CLIENT_ID	Google OAuth client ID	String	your-client-id.apps.googleusercontent.com
NEXT_PUBLIC_API_URL	Base URL for API endpoints	URL string	https://api.example.com
NEXT_PUBLIC_MIXPANEL_TOKEN	Mixpanel analytics token	String	your-mixpanel-token
NEXT_PUBLIC_SENTRY_DSN	Sentry error tracking DSN	URL string	https://your-sentry-dsn

5. 📁 Folder Structure

a. Backend Folder Structure

.
├── firebase.dev.json                       # Firebase configuration for development
├── firebase.json                           # Firebase configuration
├── package.json                            # Project metadata and dependencies
├── package-lock.json
├── src
│   ├── config.ts                           # Main configuration, index, and routes configuration
│   ├── controllers
│   │   ├── analyticsController.ts          # Controller for analytics
│   │   ├── authController.ts               # Controller for login, register, forgot password, and reset password
│   │   ├── domainController.ts             # Controller for domain management
│   │   └── shortenController.ts            # Controller for URL shortening, including malicious URL detection
│   ├── database
│   │   ├── blacklistedEmail.ts             # Contains blacklisted email addresses
│   │   └── firestore.ts                    # Firestore initializer
│   ├── error
│   │   ├── error.ts                        # Common response error handler
│   │   └── serviceError.ts                 # Common service error exceptions
│   ├── index.ts
│   ├── log
│   │   └── log.ts                          # Logger configuration using Winston
│   ├── middlewares
│   │   ├── authorization.ts                # Middleware for authorization
│   │   └── superuserAuthorization.ts       # Middleware for superuser (admin) authorization
│   ├── routers
│   │   ├── analyticsRouter.ts              # Router for analytics
│   │   ├── authRouter.ts                   # Router for authentication
│   │   ├── domainRouter.ts                 # Router for domain management
│   │   └── shortenRouter.ts                # Router for URL shortening
│   ├── types
│   │   ├── analytics.ts                    # Types for analytics
│   │   ├── auth.ts                         # Types for authentication
│   │   ├── domain.ts                       # Types for domain management
│   │   └── shorten.ts                      # Types for URL shortening
│   └── utils
│       ├── mailer.ts                       # Mailer service for sending emails
│       ├── s3.ts                           # S3 service for storing bulk shortened URLs in xlsx format
│       ├── validator.ts                    # Validator for request body using express validator
│       ├── webrisk.ts                      # WebRisk API service for detecting malicious URLs
│       └── wrapper.ts                      # Wrapper service for common response
├── swagger.json                            # Swagger documentation for API
├── tsconfig.json                           # TypeScript configuration
└── vercel.json                             # Vercel configuration for deployment

b. Frontend Folder Structure

Detailed Frontend Structure:

.
├── components
│   ├── common
│   │   ├── Backdrop/
│   │   ├── Banner/
│   │   ├── Button/
│   │   ├── FeatureDrawer/
│   │   ├── Icon/
│   │   ├── Input/
│   │   └── URLDrawer/
│   ├── layout
│   │   ├── Footer/
│   │   ├── Layout.js
│   │   └── Navbar/
│   ├── pages
│   │   ├── Analytic/
│   │   ├── AuthPage/
│   │   ├── BulkShortener/
│   │   ├── GenerateQR/
│   │   ├── Landing/
│   │   ├── TermsOfService/
│   │   └── URLShotener/
│   └── utils
│       ├── downloadFromS3.js
│       └── useCustomToast.js
├── config
│   ├── apiTarget.js
│   └── awsConfig.js
├── context
│   ├── AuthContext
│   │   └── AuthContext.js
│   ├── BackdropContext
│   │   └── BackdropContext.js
│   ├── DrawerContext
│   │   └── DrawerContext.js
│   └── StateManagementContext
│       └── StateManagementContext.js
├── hooks
│   ├── useMixpanelClient.js
│   ├── useMixpanelServer.js
│   └── useWindowSize.js
├── next.config.js
├── package.json
├── package-lock.json
├── pages
│   ├── 404.js
│   ├── api
│   │   ├── analytic.js
│   │   ├── auth.js
│   │   ├── bulkShortener.js
│   │   ├── generateQR.js
│   │   ├── google.js
│   │   ├── logout.js
│   │   ├── register.js
│   │   ├── resetPassword.js
│   │   ├── shorten.js
│   │   ├── [...shortLink].js
│   │   └── urls.js
│   ├── _app.js
│   ├── bulk-shortener
│   │   └── index.js
│   ├── _error.js
│   ├── index.js
│   ├── login
│   │   ├── forgot.js
│   │   ├── index.js
│   │   └── reset.js
│   ├── maintenance.js
│   ├── register
│   │   └── index.js
│   └── terms-of-service.js
├── postcss.config.js
├── public
│   ├── favicon.ico
│   ├── images
│   ├── logo.ico
│   └── vercel.svg
├── README.md
├── sentry.client.config.js
├── sentry.properties
├── sentry.server.config.js
├── styles
│   ├── globals.css
│   └── theme.js
└── tailwind.config.js

7. 🌐 API Endpoints

Base URL: /api/v1

Auth

Method	Endpoint	Description	Auth Required
POST	/auth/register	Register new user	No
POST	/auth/login	Login with email/password	No
POST	/auth/google	Login with Google	No
POST	/auth/forgot-password	Request password reset	No
POST	/auth/reset-password	Reset password with token	No

URL Shortening

Method	Endpoint	Description	Auth Required
POST	/shorten	Create short URL	No
POST	/shorten/bulk	Bulk shorten URLs from Excel	No
GET	/shorten	List user's URLs	Yes
GET	/shorten/bulk	List bulk Excel files	Yes
PUT	/shorten	Edit short URL	Yes
POST	/shorten/redirect	Get redirect info	No
PATCH	/shorten/generate-qr	Generate QR code	No

Analytics

Method	Endpoint	Description	Auth Required
GET	/analytics	Get URL analytics	Yes

Domain Management

Method	Endpoint	Description	Auth Required
POST	/domain	Create custom domain	Super User
POST	/domain/find	Check user's domain	Yes
PATCH	/domain/:id	Update domain	Super User
DELETE	/domain/:id	Delete domain	Super User
PATCH	/domain/:id/active-status	Toggle domain status	Super User
GET	/domain/all	List all domains	Super User

Authentication

Add token to request header:

Authorization: Bearer <token>

Common Request/Response Examples

Short URL Creation

POST /shorten
{
  "email": "user@example.com",
  "url": "https://example.com",
  "shorten": "custom-path",
  "subdomain": "custom"
}

Error Response

{
  "errors": [{
    "message": "Error description",
    "code": "ERROR_CODE"
  }]
}

8. 📊 Diagrams

Database Schema

URL Shortening Flow

Authentication Flow

URL Redirection Flow

Analytics Flow

Domain Management Flow

Application Flow

Component Architecture

9. 🔧 Development Notes

1. Code Style

   • Follow ESLint configuration
   • Use TypeScript for type safety
   • Follow component-based architecture

2. Performance Considerations

   • Implement lazy loading for components
   • Optimize images and assets
   • Use proper caching strategies