Architecture - Developing an approach to type matching between DJANGO API and JS frontend components

[sbland]

@sbland and @AdrianDAlessandro discussed approaches to typing view return contexts and then matching this to typescript types in the javascript components.

One approach would be to have dataclass classes as a context return type as below:

from dataclasses import dataclass

@dataclass
class UserSkillContext:
    skill: str
    category: str
    subcategory: str
    skill_level: int


@dataclass
class SkillsDataContext:
    user_skills_data: list[UserSkillContext]
    skill_levels: list[str]

    def to_dict(self) -> dict[str, Any]:
        return {
            "user_skills_data": self.user_skills_data,
            "skill_levels": self.skill_levels,
        }



class SkillProfileView(TermsAcceptedMixin, TemplateView):
    """View that renders the skill profile page."""

    template_name = "main/user-skills-profile.html"

    def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
        """Add user skills and skill levels to the template context."""
        context = super().get_context_data(**kwargs)

        returned_context = SkillsDataContext(
            user_skills_data=[
                UserSkillContext(
                    skill=user_skill.skill.name,
                    category=user_skill.skill.competency.competency_domain.id,
                    subcategory=user_skill.skill.competency.name,
                    skill_level=user_skill.skill_level.level,
                )
                for user_skill in UserSkill.objects.filter(user=self.request.user.pk)
            ],
            skill_levels=[skill_level.level for skill_level in SkillLevel.objects.all()],
        )

        context["user_skills_data"] = returned_context._to_dict()
        return context

[sueun-dev]

I'd separate the Python context model from the serialized payload that the TypeScript types describe. For the conversion step in this prototype, import asdict from dataclasses and use payload = asdict(returned_context).

The shown to_dict() leaves UserSkillContext objects inside the list. With those two dataclasses on Python 3.12.14, json.dumps(returned_context.to_dict()) raised TypeError; the asdict payload passed a JSON round trip with populated and empty lists. This was an isolated serialization test, not a Django page test. The sample also calls _to_dict() but defines to_dict().

asdict handles the nested conversion, not runtime type validation: an intentionally wrong string in skill_level: int remained a string in my test. I'd pin down the serialized field types and add a payload-shape test before deciding how to generate or maintain the matching TypeScript types. The conversion alone doesn't establish that cross-language contract.

[AdrianDAlessandro]

I think this kind of approach could be the right idea, but we need to think a bit deeper about this, in general.

Passing the data as context values is probably the wrong approach. I think we're better off writing a REST API that the visualisation code uses to get the data directly from the database. So the view will not pull anything from the database and will just provide the authenticated user, which the JS code can use to get the data.

It's a bit of a refactor, but I think it separates things more cleanly and actually makes it more tightly integrated for the type-matching question you have here.

An aside (but I think related)

We should look at refactoring the views, in general, to remove as much business logic (ie DB transactions) from them. I think this will line up with my above suggestion more nicely, also. (This thinking comes from this Django style guide)

[sbland]

I second moving business logic out of views. I've seperated the business login into a services layer on another Django project but this mostly contains query logic.
On a C# project we have used the Command Query Responsibility Segregation pattern which works well but sometimes means more boilerplate. I think the Django style guide suggests splitting services and selectors which I think is just another name for the CQRS pattern.

In Django, business logic should live in:

Services - functions, that mostly take care of writing things to the database.
Selectors - functions, that mostly take care of fetching things from the database.
Model properties (with some exceptions).
Model clean method for additional validations (with some exceptions).

[AdrianDAlessandro]

Yes, I think you are right about it being the CQRS pattern. I've just watched this video about it. The main takeaway was to only start using this pattern once you start reaching pain points that this architecture will fix. Which I think is solid advice. So I wouldn't refactor everything to match this pattern until we know for sure it's going to help.

I think it's a bit of a distraction from the main point of this discussion though. I think the solution we're looking for is making a separate API that can be used for the visualisation (and others). I think the best tool for this is Django Ninja.

The most applicable example is in their Models & Schemas Quick Start quide. It is basically the same thing that you suggested: using a dataclass-like object to define the type that can be matched on the JS side and then serialising that. But will a more tightly-coupled object and not needing to use a dictionary and lose the type information.