Devlog

Before start talking about the current version, V3, lets talk about the previous versions, what we learned from them and what we want to achieve with the current version.

V1 - MKdocs Material (2023 - Summer 2024)

At first, we used MKdocs Material, which is a great tool for documentation, and writing blogs. We write the contents in Markdown, configs in YAML, and customize theme and more. It was amazing to use CI/CD on Github actions, and Github Pages to host the website. However we started to face some limitations pretty fast.

Pros of V1

• Easy to use and setup
• Write courses content without worrying about the layout, or other idiosyncrasies. As straightforward as it could be
• Great for documentation and blogging
• SEO friendly with social cards
• CI/CD with GitHub Actions
• Customizable theme and layout
• Hosted on GitHub Pages
• Support for code syntax highlight, tables, admonitions, footnotes, images, latex, mermaid, and more
• We do not need to worry about style

Cons of V1

• Limited to static content
• Every change, even small ones, requires a full rebuild that could take 20 minutes
• Difficult to implement dynamic content or interactivity, such as adding wasm, or any other teaching activities such as quizzes, polls, etc.
• Lack of login to track user progress
• Some contributors got lost in the codebase, git and did not understand how markdown files with extensions work properly. Althought it worked for some of us, it was not intuitive for everyone.

V2 - Oracle, Coolify, Next.js, NestJS and Ghost (Summer 2024 - Spring 2025)

Trying to evolve from the limitations of V1, we decided to use Next.js + Typeorm for the frontend, NestJS for the backend, and Ghost for the blog as an easy win. The biggest achievemnt of this version is the ability to implement a chess competition for AI classes where the students could implement their bots and play against each other, and the ability to render MD in the way we wanted, adding any type of custom tags, quizzes, code challenges, and more. We also used Coolify to manage our deployments in the Oracle Cloud, which was a great experience until we tried to upgrade it and lost all our deployments.

Pros of V2

• Oracle cloud offers a free tier with 4 cpus, 24 GB RAM, and 200 GB storage, which is great for our needs
• Coolify was used to manage our deployments in the oracle cloud, and it was really easy to use
• Ghost is really great for blogging, posts, amazing speed, and great SEO
• Next.js gave us a powerful tool to build the frontend in the way we wanted, with all the goodies we ever wanted. We even build the ai chess competition engine there, plus we implemented a C++ compiler in the browser using WASM and Emscripten to allow students to write their bots in C++ and play against each other. And we created a dedicated section for courses to renden enriched markdown files with custom tags for quizzes, code challenges, and more.
• V0.dev helped us a lot to speedup the development with solutions for common pages like login, register, and more
• NestJS with Typeorm was the natural choice for the backend, and it was easy to implement the API

Cons of V2

• When we tried to upgrade Coolify from their v3 to v4, we lost all our deployments, which we chose to rebuild from the ground up.
• Ghost stores files locally, and once we had the problem with Coolify, we were able to recover the database, but not the files, and the original authors did not had the interest to add them back. Another issue with Ghost was the problematic integration with Next.js and NestJS, styles being lost or not being applied.
• NestJS with Typeorm lacks CRUD operations, and we tried to mitigate with nestjsx/crud but it was not enough, and we had to implement a lot of custom code, for "simple" things like permissioning, filtering, sorting, pagination, and more.
• Typeorm simply does not offer the flexibility to run complex queries, and we had to use raw SQL queries, which is not ideal, human error prone, and not type safe. We tried prisma, but it was way worse than what we had.
• The auth flow in Next.js was not well integrated with NestJS, and we ended up with 2 tokens, one for the frontend and one for the backend, which was not ideal.
• Dependency hell happened with Next.js and NestJS, where we had to use specific versions of packages to make them work together, which was a nightmare to maintain.

v3 - Self-Hosted, Next.js, ASP.NET Core + Entity Framework + HotChocolate, GraphQL, Minio and more (Summer 2025 - ...)

In this new approach we took full control of every single aspect of the project in order to avoid the problems we faced, from the frontend to the backend, and even the storage. We are using Next.js for the frontend, ASP.NET Core with Entity Framework for the backend, and Minio for storage. We are also using HotChocolate for GraphQL, which is a great tool to build APIs.

Pros of V3

• Self-hosted solution on my old computer with 64GB ram, cpu 20 cores, raid 6 with around usable 4TB of data, and 1Gbps internet connection
• Coolify is still used to manage frontend, backend, minio(storage), weekly automatic backup to an external location, notifications and alarms going directly to discord
• ASP.NET Core builds and run way faster than JavaScript projects with node, giving us a great performance boost and fast iterations
• Entity Framework allowed us to write complex queries in a type-safe way, and we can use LINQ to query the database, which is a great experience, which would be impossible with Typeorm by requiring to write raw SQL queries
• HotChocolate is a great tool to build GraphQL APIs, and it integrates well with ASP.NET Core and Entity Framework
• Minio is a great alternative to AWS S3, and it is a full S3 replacement and fully compatible with S3 APIs libs.
• Next.js we started using AI to help us fill the gaps to speedup the development.

Cons of V3

• Self-hosted requires more care and maintenance, but we didn't face issues... yet. Probably we will face issues with scaling.
• Coolify it is still a great tool, but we will need better scaling solutions in the future, prabably we should use rancher + kubernetes, maybe?
• ASP.NET Core so far, no problems, but it is way more verbose than NestJS
• Entity Framework has some flaws regarding entity relations creation, the fluent API is not as intuitive as it could be, as well the many to many can be confusing, but it is way better than Typeorm.
• HotChocolate is great for GraphQL, and requires to reimplement the types, queries, mutations, and subscriptions, which is a lot of work, but it is worth it, because the front can just get the description of the schema and generate the types, queries, mutations, and subscriptions automatically, which is a great experience.
• Minio we still do not have a good way to sync and backup all the files to an external location for extra resiliency.
• Next.js is being used heavilly with AI tools. And the criticism is mostly regarding the AI hallucinations. It keep creating files without checking the the functionality is already there. We had to lower our code quality and standards to make it work. In the next version we will revisit everything and improve the code quality, and remove the AI generated code that is not up to our standards.