Starting a sample project on Kuroco
This tutorial explains how to start a project on Kuroco, using the case of a membership-based in-house portal site as an example. It summarizes the steps to take, what tools are required, and the roles and functions of each tool. Use this as a reference for designing your project flow.
Note: Different specifications, members, and tools are required depending on the project. This tutorial is only meant to be a reference guide.
Project summary
This tutorial assumes the following details for your project.
Website specifications
- Construction of membership-based in-house portal site
- New domain acquisition
Frameworks
You will be using the following frameworks:
| Framework | Description |
|---|---|
| Kuroco | Back-end system |
| Vuetify | UI framework |
| Figma | Interface design tool |
Scope and personnel
The table below outlines the project scope and the personnel in charge (PIC) of each piece:
| Step | Phase | Scope | PIC |
|---|---|---|---|
| 1 | Project design | Requirement definitions, system, and UX design | PM, designer |
| 2 | Page and UI design | PM, designer | |
| 3 | Data structure and API design (Kuroco) | Back-end engineer, front-end engineer | |
| 4 | Design | UI design | Designer |
| 5 | Coding | Coder | |
| 6 | Development | Microservice development | Back-end engineer |
| 7 | API settings | Back-end engineer, front-end engineer | |
| 8 | External API integration | Back-end engineer | |
| 9 | Front-end build (including API calls) | Front-end engineer | |
| 10 | Environment build | Back-end engineer | |
| 11 | Data transfer | Back-end engineer | |
| 12 | Testing | Comprehensive test | QA tester |
| 13 | Operation check (acceptance) | Client | |
| 14 | Release | Release | PM |
| 15 | Management | Site operation | PM, back-end engineer, front-end engineer |
Management tool
To simplify project management and communication, limit yourself to the tools below. Doing so reduces the risk of oversight.
| Tool | Function | Description |
|---|---|---|
| Google Sheets | Design | For page lists, deadlines for each page, status management, issue management, and other tasks. (See: WBS & sample task list) |
| Backlog | Issue management, minutes sharing | Can be used to manage/share issues and meeting minutes, both internally and externally. |
| Slack | Communication | Communication tool |
| Google Meet | Communication | For video calls and conferences. |
Communication plan
Set up internal and client meetings as follow:
| Meeting | Description | Participants | Frequency |
|---|---|---|---|
| Kickoff | Held at the start of the project. | All members | One-off meeting |
| Regular meeting (client) | Progress meeting with client.(*) | Members involved in the respective phases | Once a week |
| Regular meeting (internal) | Progress meeting with internal staff. | Internal members | Once a week |
| Site management lecture | Client-oriented lecture on how to manage their site. | All members | One-off meeting (management phase) |
*Regular meeting agenda
The agenda for regular meetings is as follows:
- Specification check
- Verification of points regarding the specifications that are unclear.
- Suggestions on how to implement the site in Kuroco.
- Progress check
- Confirmation of schedule, project progress, and remaining issues.
- Addressing issues and questions in cases of delay.
1. Requirement definitions, system, and UX design
A. Create a site map
Create a site map in Google Sheets for verifying the desired pages and features with the client.
B. Define the components on each page
Define and verify the components for each page based on the site map. Components common to multiple pages can be grouped together.
C. Verify the operating environment
Verify the operating environment of the project with the client.
2. Page and UI design
Create wireframe
Create a Figma wireframe based on the site map and page components.
3. Data structure and API design (Kuroco)
A. Data structure
Design the data structure to be configured using Kuroco. This includes:
- Content structure
- Group settings
- Member item definition
For more information, see:
B. API design
To design APIs using Kuroco, first identify the required APIs based on the components of each page.
Make an API list in a Google Sheet. Also, list the API endpoints used on that page in the PageList of the Google Sheet.
At this stage, the front-end developer describes which API to use on the wireframe, and the back-end developer manages the API specifications.
4. UI design
Use your Figma wireframe directly for the UI design.
After the UI has been created, a meeting is held with the design staff and the client. To go over the elements and specification details for each webpage. Make changes if necessary, and obtain reviews and approvals from everyone on the spot.
5. Coding
This project uses Vuetify for static coding.
In some cases, it is better to use APIs instead of behavioral components. We suggest information sharing between the coding staff and API designers when designing the APIs.
6. Microservice development
Once the design is approved, you can proceed to the development phase.
A. Sign up for Kuroco
Sign up on Kuroco's Free trial page.
B. Create a development repository on GitHub
Create a development repository on GitHub and use the front-end to manage Git.
(See: GitHub Docs - Create a repo for a detailed tutorial.)
C. Configure KurocoFront hosting and Git integration
Link the GitHub repository to Kuroco using KurocoFront.
(See: How to deploy the source from GitHub to KurocoFront for a detailed tutorial.)
D. Kuroco admin panel settings
Configure the relevant settings on the Kuroco admin panel.
Content structure (extended columns)
Configure the content structure according to 3. Data structure and API design (Kuroco).
See:
Member extra information
Modify the group and member settings.
See:
7. API settings
Configure the API according to 3b. API design.
See:
8. External API integration
Integrating Kuroco with external services allows you to extend the range of available functions.
A. SendGrid settings (from e-mail address)
To use your custom domain as the from e-mail address for inquiry responses and site notifications, you need to set up a free SendGrid account and configure the relevant settings.
Note: You do not need a SendGrid account if you intend to use @kuroco-mail.app as your e-mail domain.
(See: How to link with SendGrid for a detailed tutorial.)
B. Google Analytics settings
You can track conversions on your site by integrating it with Google Analytics.
(See: How to link Google Analytics for a detailed tutorial.)
9. Front-end build (including API calls)
A. Call the API
Call the API you created from the front-end.
B. Run the API
While you are developing the front-end, test if you can retrieve the content via the API. You can use Swagger to verify the API function.
(See: How to check the data structure using Swagger UI for a detailed tutorial.)
10. Environment build
Now, build the environment for the release. To do so, acquire a custom domain and apply it to your project website.
In this tutorial, we are building a website with authentication, which requires a front-end domain and an API domain. Therefore, proceed on the premise of configuring two domains.
(This is because some web browsers do not allow third-party cookies, causing login errors in such cases. See: Google delays blocking third-party cookies in Chrome until 2023 for more information on this issue.)
A. Get the original domains
Acquire the two domains below:
| Domain | Description |
|---|---|
www.CLIENT.app | Front-end domain |
kuroco.CLIENT.app | API domain |
B. Configure the domain settings
Apply your custom domains to KurocoFront and set up the following:
- DNS for the front-end domain
- DNS for the API domain
- Domain on Kuroco's admin panel
(See: Using your own custom domain name on KurocoFront for a detailed tutorial).
11. Data transfer
Register the required contents and user data on the Kuroco admin panel. You can fill in the respective forms manually or batch upload the data in a CSV file.
(See: Bulk upload via CSV for a detailed tutorial).
12. Comprehensive test
A. Create the test cases
Create test cases as you proceed with the development.
B. Perform an internal test
Conduct internal verifications based on your test cases. Any issues found will be logged and corrected by task management and re-verified.
13. Operation check (acceptance)
Client-side verification
After the internal comprehensive test, ask your client to verify the project. Deploy the project in the development environment for the client to test it. During this step, restrict access to the project through IP address or basic authentication. Make modifications based on the client feedback.
Refer to the FAQ What is kuroco_front.json? -> basic: Basic authentication for more information.
14. Release
After the operation check is complete, the project is ready for release.
Deauthorization
Don't forget to remove the IP address and basic authentication restrictions placed in step 13.
15. Site operation
The operation phase starts upon the site launch. Prepare the user guide documentation and support your client to operate their website independently.
Support
If you have any other questions, please contact us or check out Our Slack Community.