Problem Statement
The current setup for the Marketing site, Hacker Portal App, and Docs site is fragmented and inefficient. This makes maintenance more time-consuming, leads to inconsistent branding, makes duplicated effort more difficult to track, and can result in performance issues. Plus, the content isn't localized.
Our code is currently fragmented across separate repositories. Design elements, utilities, and configurations are strewn around the GitHub organization. Developers currently need to context switch between different repositories. This hurts their experience and overall productivity.
Residual unversioned files can also increase the risk of deep, catastrophic bugs may not be caught by tests and hurt the project.
Goals
Establish a unified design system for a consistent brand identity.
Improve development efficiency and reduce maintenance by consolidating into a monorepo.
Enable server-side rendering for the marketing site to boost performance.
Implement a CMS for easier content updates without changing code.
Localize content to support multiple languages.
Implement unit, integration, and end-to-end tests for code quality.
Use a monorepo management tool to streamline configurations and support micro-frontend architecture.
Out of Scope
Major redesigns of user interfaces for the marketing site, hacker portal app, and docs site for V1.
Performance optimizations beyond initial server-side rendering for the marketing site.
Full internationalization beyond the initial setup for content localization.
Solution Summary
History/Context
Currently, the marketing site uses vanilla React and Vite, the hacker portal app is a full-stack application with lots of client-side interactions, and the docs site runs on Fumadocs with Next.js. The marketing site is static and client-side rendered, with hard-coded content. This setup makes it tough to maintain consistent branding, update content, and manage shared configurations.
Solution
Consolidate all three web assets into a monorepo managed by Nx. Here's the plan:
Set up a design system documented with Storybook and Figma to unify development and design.
Move the marketing site to a server-side rendered solution using Next.js, with content managed by Payload CMS.
Make sure the hacker portal app and docs site use shared configurations and components from the design system.
Localize all content to support multiple languages.
Implement unit, integration, and end-to-end tests to ensure code quality and reliability.
Changes in terminology:
Rename the entire monorepo from hackathon to 2025. This way the next team can have 2026, and so on and so forth. The monorepo should be integrated instead of package-based, and contain all of our projects and sub-projects that we work on. Whether it's hardware or software. All code and assets can be shared. Makes scripting, scaffolding, codegen, devops, and enforcing architecture with module boundaries much easier. You can create and link toolchains too. Employ a single version policy, and the semver bot will use the conventional commits to auto-generate changelogs.
Landing Page referred to as website moving forward. Conventional commit scope will be web. So feat(web/components): change nav bar button background colors to a hotter pink. We'll have a memory url 2025.cuhacking.ca. After the hackathon's over, and the next team's ready to replace it with a new design and a new website, The memory url will host what cuhacking.ca looked like before it was replaced. Their memory url will be 2026.cuhacking.ca, and so on so forth for future teams. We can say "It's on the site", and that means the website.
Docs Site refers to the docs site. No rocket science here. Conventional commit scope is docs. So fix(docs/contribution-guidelines): update conventional commit scopes. Give this two urls, docs.cuhacking.ca, and 2025.cuhacking.com/docs. Same idea. docs.cuhacking.ca, is the redirect url, and the 2025.cuhacking.com/docs will stay up forever as a memory. Next iteration of docs.cuhacking.ca will be owned by the next dev team and they'll also have 2026.cuhacking.com/docs as the memory url. We can say "It's on the docs" or "It's on our docs", and that means the Docs Site. This is inspired by how the Rust Programming language affectionately refers to their book as "the book".
Hacker Portal refers to our crown jewel, the hacker portal. Conventional commit scope is portal. I think that's a bit wordy so I'm fine with using app, but we'll run into issues with that later when we have other apps. Redirect url is portal.cuhacking.ca, and the memory url is 2025.cuhacking.com/portal. We can say "It's on the portal", and that means the Hacker Portal. It should never be ever referred to as a website because it isn't one. It's a highly dynamic web app with pages and states.
Get all past websites of cuHacking up and and have a toggle/dropdown in our navbar that links to all past iterations, as lots of people before us worked hard on them. Send all the cuhacking alumni an email that we got them up as a homage of respect and they can re-visit them. This kickstarts a strong alumni network.
Other options considered
Turborepo has been looked into, but Nx has been deemed to be a better fit due to its provider-agnostic features. Evaluation matrices can be found on Monorepo.tools.
Keeping separate repositories: This was dismissed because it would increase maintenance efforts and make it harder to manage shared configurations and consistent branding.
MFarabi619
commented
1 month ago
Problem Statement The current setup for the Marketing site, Hacker Portal App, and Docs site is fragmented and inefficient. This makes maintenance more time-consuming, leads to inconsistent branding, makes duplicated effort more difficult to track, and can result in performance issues. Plus, the content isn't localized.
Our code is currently fragmented across separate repositories. Design elements, utilities, and configurations are strewn around the GitHub organization. Developers currently need to context switch between different repositories. This hurts their experience and overall productivity.
Residual unversioned files can also increase the risk of deep, catastrophic bugs may not be caught by tests and hurt the project.
Goals
Out of Scope
Solution Summary
History/Context Currently, the marketing site uses vanilla React and Vite, the hacker portal app is a full-stack application with lots of client-side interactions, and the docs site runs on Fumadocs with Next.js. The marketing site is static and client-side rendered, with hard-coded content. This setup makes it tough to maintain consistent branding, update content, and manage shared configurations.
Solution Consolidate all three web assets into a monorepo managed by Nx. Here's the plan:
Changes in terminology:
hackathonto2025. This way the next team can have2026, and so on and so forth. The monorepo should be integrated instead of package-based, and contain all of our projects and sub-projects that we work on. Whether it's hardware or software. All code and assets can be shared. Makes scripting, scaffolding, codegen, devops, and enforcing architecture with module boundaries much easier. You can create and link toolchains too. Employ a single version policy, and the semver bot will use the conventional commits to auto-generate changelogs.Landing Pagereferred to aswebsitemoving forward. Conventional commit scope will beweb. Sofeat(web/components): change nav bar button background colors to a hotter pink. We'll have a memory url2025.cuhacking.ca. After the hackathon's over, and the next team's ready to replace it with a new design and a new website, The memory url will host whatcuhacking.calooked like before it was replaced. Their memory url will be2026.cuhacking.ca, and so on so forth for future teams. We can say "It's on the site", and that means the website.Docs Siterefers to the docs site. No rocket science here. Conventional commit scope isdocs. Sofix(docs/contribution-guidelines): update conventional commit scopes. Give this two urls,docs.cuhacking.ca, and2025.cuhacking.com/docs. Same idea.docs.cuhacking.ca, is the redirect url, and the2025.cuhacking.com/docswill stay up forever as a memory. Next iteration ofdocs.cuhacking.cawill be owned by the next dev team and they'll also have2026.cuhacking.com/docsas the memory url. We can say "It's on the docs" or "It's on our docs", and that means the Docs Site. This is inspired by how the Rust Programming language affectionately refers to their book as "the book".Hacker Portalrefers to our crown jewel, the hacker portal. Conventional commit scope isportal. I think that's a bit wordy so I'm fine with usingapp, but we'll run into issues with that later when we have other apps. Redirect url isportal.cuhacking.ca, and the memory url is2025.cuhacking.com/portal. We can say "It's on the portal", and that means the Hacker Portal. It should never be ever referred to as a website because it isn't one. It's a highly dynamic web app with pages and states.Get all past websites of cuHacking up and and have a toggle/dropdown in our navbar that links to all past iterations, as lots of people before us worked hard on them. Send all the cuhacking alumni an email that we got them up as a homage of respect and they can re-visit them. This kickstarts a strong alumni network.
Other options considered