Where does the Pythagorean theorem "fit" within modern mathematics?

Length, in Euclidean geometry, is a relation, not a number. We say that two segments are of the same length if they are congruent to each other, and congruence is one of the undefined notions of Euclidean geometry. The Pythagorean theorem comes about as soon as you decide to map lengths to positive real numbers, and it does so because of how length and angles are related by the congruence and similarity axioms (e.g., how the Pythagorean theorem is proved).

Lengths, in vector spaces, can be anything that satisfies the axioms for a norm. But to have a Pythagorean theorem, you need a notion of perpendicularity of vectors, that is, an inner product, which exists only if the norm satisfies the parallelogram law. For example, the taxicab norm, which is given by $|(a,b)|=|a|+|b|$ does not come from an inner product and there is no Pythagorean theorem for that notion of length.

The natural question is why does the Pythagorean theorem in Euclidean geometry correspond to the Pythagorean theorem in a finite dimensional vector space over the reals with an inner product? (there is a theorem that states that in a finite-dimensional vector space there is only one inner product up to isomorphism, so we really can talk about THE Pythagorean theorem).

The answer is that the finite dimensional vector space over the reals with an inner product encodes the congruence and similarity axioms of Euclidean geometry. The basic exposition of (most of) this can be found in the first half of Chapter 2 of Emil Artin's wonderful book Geometric Algebra.

Take a geometry of points and lines for which the following statements are true:

1. Any two points determine a line.
2. Parallel postulate: for any point $p$ not on line $\ell_1$ there exists a unique line $\ell_2$ that passes through $p$ but doesn't intersect $\ell_1$.
3. Non-triviality: there exist $3$ non-collinear points.
4. Desargues' Theorem (the wiki article is horrible)

The first three statements allow you to define translations (transformations of the plane that send lines to parallel lines and have no fixed points), while the fourth allows you to a construct a field over which the space of translations is a $2$-dimensional vector space, and such that if you associate translations $OP$ and $OQ$ with $(0,1)$ and $(1,0)$, then any point $R$ has a translation $OR$ which can be written as $(a,b)$ with $a$ and $b$ in the field.

In this way, any affine Desarguesian plane (thing that satisfies statements 1, 2, 3 and 4) can be identified with a $2$-dimensional vector space over some field (and conversely any $2$-dimensional vector space over some field corresponds to an affine Desarguesian plane).

Alright. Now, Euclidean geometry satisfies Desargues' Theorem, so which field does it correspond to? Well, it turns out that the fact that the geometry is ordered (i.e., we have a notion of an ordering of points on a line) means that the field has to be ordered and thus is a subfield of the real numbers (this is where we need something like the continuity or Hilbert's completeness axiom which roughly state that things that should intersect do intersect, and imply that the base field is all of the real numbers).

Then the whole inner product shebang turns out to just be a codification of the various congruence axioms. The norm is given by choosing some vector to make a unit vector (segment) and then considering to which vector in the same direction other vectors (segments) are congruent to. The inner product is a matter of encoding the notion of angle between vectors as an inner product, i.e., as a function linear in both vectors, which essentially takes the notions of similarity, congruences and unit circles.

It turns out that you can do all of this in the reverse direction, and so the Euclidean plane really is a 2-d vector space over the reals with an inner product.

Addendum: a comment on symmetry groups that is too long to leave as a comment.

Every norm on a vector space has its own unit blob, that is, the set of vectors with norm less than one. Geometrically, blobs that correspond to a norm satisfy the following properties: they are convex, they are absorbing (every vector is a multiple of a vector in the blob), and they don't contain any lines through the origin. It is a theorem that any such blob corresponds to a norm.

As we know, the transformations of a vector space are linear transformations, which means that the symmetry group of an object in your vector space is going to consist of the linear transformations that bijectively send an object to itself. In other words, the group of symmetries of an object is the set of invertible linear transformations that fix that object.

Now, the blob of the Euclidean norm is the unit disk, and the unit circle is the boundary of the disk. The unit circle is the set of vectors with Euclidean norm $1$, and in general, the boundary of the unit blob for a norm will be the set of vectors with norm $1$. The group of symmetries of the boundary of the blob then will be the set of invertible linear transformations that send vectors with norm $1$ to vectors with norm $1$.

A slight caveat is that you don't want to consider just any old invertible linear transformations because when you add a norm to a vector space, you are in effect defining a topology, that is, a way to define continuity. As a result you want to work with continuous linear transformations. BUT! In a finite dimensional vector space, no matter what the norm, we have that every linear transformation is continuous.

What this means is that for any norm on, say the $2$-d vector space over the reals, the symmetry groups of the boundary of the unit blob are all invertible linear transformations of the same space. Hence, we can directly compare these groups to each other since they live in the same space (of invertible linear transformations of $\mathbb R^2$).

Example: the boundary of the unit blob for the Euclidean norm is the unit circle, i.e., all points such that $x^2 + y^2=1$. The boundary of the unit blob of the Taxicab norm is the unit diamond, i.e., all points such that $|x|+|y|=1$.

Now if you think about it, any linear transformation that sends the unit diamond to itself will also send the unit circle to itself. Hence, the symmetry group for the Euclidean norm contains the symmetry group for the Taxicab norm, and in fact it contains it properly since, for example, rotation by $45$ degrees fixes the circle, but doesn't fix the diamond.

The Pythagorean theorem follows directly from the basic properties of the dot product: if $x \cdot v = 0$, then $(x + v) \cdot (x + v) = x \cdot x + v \cdot v$. There is not much to say about this proof from a modern point of view except that it does not depend on the finite-dimensionality of the underlying space, e.g. in Hilbert spaces it even generalizes to Parseval's identity. (Of course one then has to prove that dot products induce norms, but this is the standard Cauchy-Schwarz argument.)

I would like to interpret your title question more broadly. My impression is that mathematicians do not really think about the Pythagorean theorem directly (unless, perhaps, they are functional analysts!). Rather, following Klein's Erlangen philosophy, they think about the group of symmetries that the use of the Pythagorean theorem (really, dot products) implies. In the plane, this is the Euclidean group $\text{E}(2)$, in which sits the orthogonal group $\text{O}(2)$ of linear transformations preserving the dot product (rotations and reflections). The geometry determined by the Euclidean group is one where it makes sense to talk about lengths and angles and all the familiar tools of Euclidean geometry. There are other Lie groups which determine other types of geometries (the "non-Euclidean" ones).