diff --git a/_config.yml b/_config.yml index 01783fc..94134e3 100644 --- a/_config.yml +++ b/_config.yml @@ -1,10 +1,14 @@ title: RAS-Backend Documentation description: A guide to understanding the backend server of RAS. theme: just-the-docs +logo: "/assets/images/spoLogo.webp" + callouts: info: title: Information color: green +search: + button: true note: title: Note - color: blue \ No newline at end of file + color: blue diff --git a/docs/cmd.md b/docs/cmd.md deleted file mode 100644 index ed23942..0000000 --- a/docs/cmd.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title : cmd -layout : default -nav_order: 7 ---- \ No newline at end of file diff --git a/docs/cmd/admin.md b/docs/cmd/admin.md new file mode 100644 index 0000000..f6c4350 --- /dev/null +++ b/docs/cmd/admin.md @@ -0,0 +1,53 @@ +--- +title : admin +layout : default +nav_order: 1 +parent : cmd +--- + +# admin.go + + + +The Go viper package is used to read the [config.yaml configuration constants file]() and get the port of the various administrator services. A new Go engine is initialized and the required middlewares are attached to it. + + +## function adminRCServer +It returns an http server instance for listening to requests of the mail service. + +{: .info} +The adminRC service is hosted on port 3490. + +### Middlewares Attached to the process +- [CORS]() : Custom middleware to allow cross-origin requests. +- [Authenticator]() : Custom middleware to get the role ID of the user using the service. +- [EnsurePsuedoAdmin]() : Custom middleware to ensure that the role ID is that of a pseudo admin. (OPC, GOD, APC and Chairman) +- Recovery +- Logger + +Initialized service is passed to [adminRC router](). + +## function adminApplicationServer +Same as [adminRCServer]() except the fact the service is passed to [Application admin router](). + +{: .info} +The adminApplication service is hosted on port 3492. + +## function adminCompanyServer +Same as [adminRCServer]() except the fact the service is passed to [Company admin router](). + +{: .info} +The adminCompany service is hosted on port 3495. + +## function adminStudentServer +Same as [adminRCServer]() except the fact the service is passed to [Student admin router](). + +{: .info} +The adminStudent service is hosted on port 3500. + +--- +#### References +- [Go Engines]() +- [Go Logger middleware]() +- [Go recovery middleware]() +- [Go Viper module]() \ No newline at end of file diff --git a/docs/cmd/auth.md b/docs/cmd/auth.md new file mode 100644 index 0000000..583590e --- /dev/null +++ b/docs/cmd/auth.md @@ -0,0 +1,33 @@ +--- +title : auth +layout : default +nav_order: 2 +parent : cmd +--- + +# auth.go + +This file configures the mail service handler for the authentication service. + +## function authServer +It returns an http server instance of the started server for broadcasting content on the mail channel. + +The Go viper package is used to read the [config.yaml configuration constants file]() and get the port of the authentication service. A new Go engine is initialized and the required middlewares are attached to it. + +{: .info} +The authentication service is hosted on port 3475. + +### Middlewares Attached to the process +- CORS - Cross-Origin Resource Sharing : Custom middleware to allow cross-origin requests. +- Recovery (Standard Go middleware) : to recover from any panic +- Logger (Standard Go Middleware) : To log the status +- Gin middleware + +Initialized service is passed to [auth router]. + +--- +#### References +- [Go Engines]() +- [Go Logger middleware]() +- [Go recovery middleware]() +- [Go Viper module]() \ No newline at end of file diff --git a/docs/cmd/cmd.md b/docs/cmd/cmd.md new file mode 100644 index 0000000..d5fecea --- /dev/null +++ b/docs/cmd/cmd.md @@ -0,0 +1,31 @@ +--- +title : cmd +layout : default +nav_order: 7 +has_children: true +--- + +# main.go + +A mail service is initialized in a goroutine and passed on to the following handlers. The errors are returned to the main function and logged by the logger. + +{: .info} +Mail read and write API call timeouts are defined to 5 seconds and 10 seconds respectively. The mailer works instantly. + +The service is passed on to the following handlers. The handlers are defined in the [overview]({{ site.baseurl }}{% link docs/overview.md %}) for reference. + +- Auth +- RAS +- Student +- Company +- Admin RC +- Admin Application +- Admin Student +- Admin Company + +--- +#### References +- [chan - Go Command](https://www.sohamkamani.com/golang/channels/) +- [errgroup](https://pkg.go.dev/golang.org/x/sync/errgroup) +- [Go Routines](https://go.dev/tour/concurrency/1) +- [Gin multiple port http services](https://github.com/gin-gonic/gin/issues/346) \ No newline at end of file diff --git a/docs/cmd/company.md b/docs/cmd/company.md new file mode 100644 index 0000000..a033dae --- /dev/null +++ b/docs/cmd/company.md @@ -0,0 +1,9 @@ +--- +title : company +layout : default +nav_order: 3 +parent : cmd +--- + +# company.go +Similar to other handler files, this file configures the mail service handler to be passed to the company router. \ No newline at end of file diff --git a/docs/cmd/ras.md b/docs/cmd/ras.md new file mode 100644 index 0000000..ac53b25 --- /dev/null +++ b/docs/cmd/ras.md @@ -0,0 +1,12 @@ +--- +title : ras +layout : default +nav_order: 4 +parent : cmd +--- + +# ras.go +Similar to other handler files, this file configures the mail service handler to be passed to the ras router. + +{: .info} +The RAS service doesn't require authentication as is is just used to test the mail service and send a testing mail. \ No newline at end of file diff --git a/docs/cmd/student.md b/docs/cmd/student.md new file mode 100644 index 0000000..7eb23b5 --- /dev/null +++ b/docs/cmd/student.md @@ -0,0 +1,10 @@ +--- +title : student +layout : default +nav_order: 5 +parent : cmd +--- + +# student.go + +Similar to other handler files, this file configures the mail service handler to be passed to the student router. \ No newline at end of file diff --git a/docs/errors/errors.md b/docs/errors/errors.md new file mode 100644 index 0000000..c8e8288 --- /dev/null +++ b/docs/errors/errors.md @@ -0,0 +1,9 @@ +--- +title : Logged Errors +layout : default +nav_order: 17 +has_children : true +--- + +# Common logged errors +This file lists down the various common errors encountered while developing, building and deploying the application. \ No newline at end of file diff --git a/docs/mail.md b/docs/mail.md index 721aeab..2554fdb 100644 --- a/docs/mail.md +++ b/docs/mail.md @@ -2,4 +2,55 @@ title : mail layout : default nav_order: 11 ---- \ No newline at end of file +--- +# config.go +This file initializes the mailer with the required constants. Viper is used to get the constants from [_config.yml]() and the [secrets file](). Logrus is used to log the status. + +Following constants are initialized +- user +- sender : user + "@iitk.ac.in" +- pass : password +- host +- port +- webteam : email address of the web-team + +{: .info} +user, password, webteam are defined in the secrets file. + +--- +# service.go +This file defines methods to build messages. + +Mail struct is defined with the standard mailing properties. +- To +- Subject +- Body + +## Function BuildMessage +This method builds the message by setting the From, Subject, To and Signature properties of the body of the mail and returns the final body. + +[Read the code here]() + +{: .info} +All the recipients are put into BCC when the message is mass mailed. + +## Function Service +This is the function started in [cmd]() as a Go routine for sending mails. The function receives the mail queue channel, builds the message of the mail using [BuildMessage function]() and sends the mail using the SMTP protocol. + +Errors are logged by logrus. + +{: .info} +The mail is forwarded to the webteam mail as well + +--- +# generate.go +This file takes all the properties of the mail and generates the final object of type Mail to be sent using the SMTP protocol. + +- **Function GenerateMail** - to generate a single mail +- **Function GenerateMails** - to generate multiple mails + +--- +#### References +- [logrus middleware](https://pkg.go.dev/github.com/sirupsen/logrus#section-readme) +- [A Tour of Go](https://go.dev/tour/concurrency/1) - Do check this out +- [SMTP Documentation](https://pkg.go.dev/net/smtp) \ No newline at end of file diff --git a/docs/overview.md b/docs/overview.md index c6b6f05..cd8f5ce 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -3,3 +3,31 @@ title : Overview layout: default nav_order: 2 --- +# Overview +The application is divided into multiple sections and follows a sort of neomonolith architecture. The different sections of the application use separate ports for increased stability. A crash at one of the ports/handler leaves the others remain unaffected. + +## RAS: 3470 +This is the testing handler. It is used to get ping responses from the server. It is also used to test the connection to the mail controller. + +## AUTH: 3475 +This handler is responsible for authentication of the user. It is responsible for checking the credentials of the user and returning the appropriate response. It also handles the registration of new users. + + +## STUDENT: 3480 +This handler has all the routes related to the student. It is responsible for handling the requests related to the student's application, profile, etc. + +## COMPANY: 3485 +This handler has all the routes related to the company. It is responsible for handling the requests related to the company's new job openings, notices, application status etc. + +# ADMIN: +Overview of the admin handlers +## RC: 3490 +This handler is responsible for handling the requests related to the RC. It is used by the admin to post notices, reminders, verify resumes and answers to rc questions. + +## APP: 3492 +This handler contains all the APIs related to the admin RC events, proformas, etc. It is used by the admin to verify the proforma, add new proforma, etc. +## COMPANY: 3495 +This handler contains all the APIs related to the company. It is used by the admin to verify the company, add new company, etc. +## STUDENT: 3500 +This handler contains all the APIs related to the student. It is used by the admin to verify the student, add new student, etc. + diff --git a/docs/util.md b/docs/util.md index e00c7a8..9f04e22 100644 --- a/docs/util.md +++ b/docs/util.md @@ -2,4 +2,30 @@ title : Utils layout : default nav_order: 16 ---- \ No newline at end of file +--- + +# convert.go +This file contains utilities to parse data as required in other parts of the program. + +Functions in the file +- **ParseUint** - converts a string to an unsigned integer. Very standard implementation. If it cannot be converted, then 0 along with non-nil error is returned. + +{: .info} +>2 objects are returned (converted unsigned integer, error). + +- **ParseString** - Converts an unsigned integer to string. + +--- + +# prog_dept.go +This file contains utilities to check and compare the program departments. + +**Function isDoubleMajor** to check if the given branch ID is a double major branch ID or not. (returns boolean) + +{: .info } +> array of all double major program department IDs +> +> 28: AE | 29: BSBE | 30: CE | 31: CHE | +> 32: CSE | 33: EE | 34: MSE | 35: ME | +> 96: CHM | 36: ECO | 37: MTH | 97: SDS | +> 98: PHY | diff --git a/index.md b/index.md index 41d6175..5524f12 100644 --- a/index.md +++ b/index.md @@ -3,5 +3,6 @@ title: Home layout: home nav_order: 1 --- -RAS-Backend Documentation ---- \ No newline at end of file +## RAS Backend Documentation +RAS is the Recruitment Automation System developed by a team of 10 undergraduate students for the Students' Placement Office, IIT Kanpur to ease-out and automate the internship and placement process of the institute. +