Technical Principles
Engineering Exists to Protect the Vision
Engineering is not a separate discipline.
It is the discipline that protects everything else.
Every architectural decision, every abstraction, every interface should serve one purpose.
Making the learning environment real.
When engineering loses connection to the vision, it optimises for the wrong things.
Speed without direction. Cleverness without clarity. Scale without purpose.
Engineering at Maigie exists to translate belief into systems that work.
Build Around the Domain
The most important architectural decision we make is this.
The domain leads. Technology follows.
We do not choose a database and then shape the domain to fit it.
We do not choose a framework and then force learning into its patterns.
We understand learning first.
Then we build systems that serve it.
The Domain Is the Source of Truth
When engineering decisions conflict with the domain model, the domain wins.
The domain represents our understanding of learning.
Technology is replaceable.
Understanding is not.
If the domain says a Learner has a relationship with a Learning Space, then the system must model that relationship clearly.
If the domain says Intelligence observes behaviour, then the architecture must enable observation.
The domain is not documentation.
It is the blueprint for everything we build.
Design for Evolution
Learning changes.
Technology changes.
Our understanding deepens.
The platform must evolve without breaking.
This means clear boundaries. Small surfaces. Independent components. Versioned interfaces.
Every decision should ask one question.
Can this change without requiring everything else to change?
If the answer is no, the design is too coupled.
Intelligence Is Part of the Platform
Artificial Intelligence is not a plugin.
It is not a service we call occasionally.
Intelligence is a fundamental capability of the platform itself.
It should be as natural as storing data or serving a response.
Every layer should be able to access intelligence when needed.
Every component should be able to contribute to intelligence when possible.
Simplicity Enables Scale
Complex systems are fragile systems.
Simple systems scale.
Simplicity does not mean fewer features.
It means fewer unnecessary dependencies. Clearer responsibilities. Smaller interfaces. Less hidden behaviour.
When something is simple, it can be understood.
When it can be understood, it can be maintained.
When it can be maintained, it can evolve.
Every Layer Has One Responsibility
A layer that does two things does neither well.
The experience layer presents. The coordination layer orchestrates. The learning layer models. The intelligence layer reasons. The foundation layer supports.
When a layer begins absorbing responsibilities from another, complexity grows exponentially.
Discipline in responsibility creates freedom in evolution.
Quality Is a Product Feature
Quality is not a technical concern hidden from users.
Quality is something learners experience directly.
Reliability. Speed. Consistency. Accuracy. Predictability.
These are product features as much as any button or screen.
Engineering owns quality.
Not as a burden.
As a responsibility to the people who depend on us.
Build for Teams
Software is built by people.
Architecture should respect that.
Clear boundaries between domains allow teams to work independently.
Shared language prevents misunderstanding.
Small interfaces reduce coordination costs.
The best architecture is one where a team can deliver value without waiting for every other team to agree.
The Key Insight
Engineering architecture should follow the domain model.
Not the other way around.
Our domain defines nine core areas.
Personal Learning. Learning Spaces. Classrooms. Knowledge. Learning Intelligence. Progress. Memory. Relationships. Institutions.
Each of these becomes a bounded context.
Each has clear ownership.
Each can evolve independently.
Each communicates through well-defined interfaces.
When the architecture mirrors the domain, engineers think in learning concepts rather than technical abstractions.
This is not a coincidence.
It is the most important architectural decision we make.
The domain shapes the code.
The code serves the domain.
Everything else follows from this.