Problem
Provide an API for departments and employees where clients can fetch subtrees, move nodes, and delete departments without corrupting the hierarchy.
Back to projects
Org Structure API
A REST API for departments and employees. Its central engineering problem is changing an arbitrary-depth tree without violating structural invariants.
- Domain
- Organisational hierarchy
- Model
- Departments and employees
- Foundation
- FastAPI · SQLAlchemy · PostgreSQL
PROBLEM & CONSTRAINTS
CRUD becomes harder when entities form a mutable tree.
Creating and reading nodes is straightforward until moves, cascading deletion, and cycle prevention are introduced.
Constraints
- A department cannot be moved inside its own subtree.
- A name must be unique among nodes sharing the same parent.
- Deletion must explicitly define what happens to child departments and employees.
- Hierarchy changes must pass through business validation rather than direct ORM updates.
ARCHITECTURE
The API layer is separated from tree integrity rules.
FastAPI and Pydantic own the contract, a service layer checks invariants, SQLAlchemy handles persistence, and Alembic controls schema evolution.
- cycle prevention
- sibling uniqueness
- explicit deletion mode
- schema migrations
TREE MUTATION FLOW
Moving a node starts by validating the tree's future state.
The operation is treated as a structural mutation with invariants rather than a simple parent_id update.
Command validation
FastAPI validates identifiers, department fields, and operation mode through Pydantic schemas.
New parent validation
The service confirms that the parent exists and that the moved node will not become its own descendant.
Sibling uniqueness
The department name is checked within the new parent scope rather than globally across the organisation.
Transactional mutation
After validation, the ORM persists the new relation and associated changes in PostgreSQL.
Consistent tree response
The API returns the updated structure only after a successful mutation, otherwise it exposes a clear error.
KEY DECISIONS
Tree invariants are represented as business rules.
The project's main value is making valid and invalid hierarchy changes explicit.
Service layer
Move, delete, and employee rules are not tied to one particular HTTP endpoint.
Cycle prevention
Before changing the parent, the service ensures the new location is not inside the node's own subtree.
Parent-scoped uniqueness
The same name may exist in separate branches, but not among sibling departments.
Alembic migrations
Database schema changes are versioned and do not rely on manual environment updates.
QUALITY
Integration tests exercise the API together with business rules.
Tests target observable service behaviour across CRUD, tree mutation, employees, and invalid operations.
Integration scenarios go through the HTTP contract and assert the results of hierarchy operations.
The PostgreSQL schema evolves reproducibly and remains versioned alongside the source code.
The application and database run as one local environment with Swagger UI available after startup.
LIMITS & HONESTY
The case presents the implemented core without treating the roadmap as finished work.
Current code is separated from capabilities and figures that still need implementation or reproducible evidence.
JWT and role separation
Authentication appears in the repository roadmap and is not presented here as an implemented capability.
Redis caching and pagination
Tree caching and employee pagination remain next steps rather than part of the current critical path.
Performance without a reproducible benchmark
README figures are not treated as production guarantees until a public methodology and runnable benchmark are included.
CI, monitoring, and visualisation
An automated pipeline, observability, and a tree frontend logically follow API contract stabilisation.
RESULT
A compact API demonstrates non-trivial data invariants.
The project is valuable not for the number of technologies, but for treating ordinary CRUD operations through the integrity of a mutable tree.
- Changing parent_id is a domain operation when it can damage the data structure.
- A roadmap and the current implementation should be clearly separated in documentation and portfolio content.
- Integration tests are especially useful where failures appear across API, service, and database boundaries.
SOURCE CODE
The tree implementation and test scenarios are available in the repository.
The README includes endpoints, Docker setup, project structure, and an explicit list of next steps.