I've worked on projects where getting the right data was the bottleneck. You can't build features without data, and sometimes the data just doesn't exist or is locked behind paid APIs. Satellite tracking is different — the orbital data is publicly available. That shouldn't be a story, but it is. Most developers never think about it because they assume someone else has already built the tracking layer. They call an external API and move on.

I didn't want to move on. I wanted to understand: how do two lines of numbers become a real-time position on Earth? And could I build that myself, with no aerospace background?

I looked at existing satellite tracking tools, but most were black boxes — they called an external API and rendered the result on a map. I couldn't see how it worked. That bugged me. I wanted to build it myself and find out.

That question led me into orbital mechanics, TLE propagation, and Orekit — a Java library used by the European Space Agency. Orekit is powerful, but almost all examples assume standalone or academic usage. There were barely any resources explaining how to integrate it into a production web backend. My progress was slow — learning by failing.

So I built Vigilance: a Spring Boot backend that takes raw orbital data and turns it into live satellite positions, pass predictions, and ground footprints. Here's what I learned about making aerospace-grade physics play nice with a web framework.

What Is a TLE and Why Does It Go Stale

A TLE (Two-Line Element Set) is two lines of 69-character data that encode everything needed to calculate a satellite's position and velocity at a specific moment. Here's the ISS:

ISS (ZARYA) 1 25544U 98067A 24101.21315433 .00002243 00000+0 48609-4 0 9991 2 25544 51.6392 59.7121 0003000 73.4153 286.7121 15.50011348397460

Those six numbers encode: inclination, RAAN (where the orbit crosses the equator), eccentricity, argument of perigee, mean anomaly, and mean motion. Think of it as a snapshot of where the satellite is and how it's moving.

But TLEs decay. I learned this the hard way: the Earth's bulge causes precession, atmospheric drag eats altitude, and after a week your position prediction could be off by kilometers. I'd watch my own predictions degrade in real time.

The US Space Force updates TLEs regularly — sometimes daily for high-value satellites, less frequently for others. Use a TLE that's a week old, and your position could be kilometers off. That's fine for some applications, but if you're predicting when a satellite flies over a ground station, you need fresh data.

The TLE Lifecycle State Machine

To handle TLE freshness, I built a state machine with five states: PENDING → ACTIVE → STALE → EXPIRED → FETCH_FAILED.

Here's how it works:

┌──────────┐         ┌──────────┐         ┌──────────┐         ┌──────────┐
│ PENDING  │────────►│ ACTIVE   │────────►│  STALE   │────────►│ EXPIRED  │
│(no data) │         │(<12h)    │         │(12-48h)  │         │(>48h)    │
└────┬─────┘         └────┬─────┘         └────┬─────┘         └──────────┘
     │                     │                     │
     │ fetch failed        │ retry success      │
     ▼                     │                     │
┌──────────┐              │                     │
│FETCH_FAIL │─────────────┘                     │
│(transient)│                                   │
└────┬─────┘                                   │
     │ 5+ failures                             │
     └─────────────────────────────────────────┘

PENDING: No data yet
ACTIVE: Fresh data (less than 12 hours old)
STALE: Getting old (12-48 hours) — still usable, should refresh
EXPIRED: Too old (48+ hours) or satellite doesn't exist
FETCH_FAILED: Tried to fetch, failed (network error, rate limit, etc.)

The refresh strategy is asynchronous. When a user requests satellite data, the service checks the TLE status. If it's STALE, EXPIRED, or FETCH_FAILED, it triggers a background refresh. The user gets the current data immediately; the system fetches fresh data in the background.

I added a distributed lock using ConcurrentHashMap.newKeySet() to prevent duplicate refreshes when multiple users request the same satellite simultaneously. There's also a 5-minute cooldown between refresh attempts to avoid hammering CelesTrak. After five failed fetches, I mark the satellite EXPIRED — catches decommissioned satellites and invalid NORAD IDs.

The state machine solves the data freshness problem, but it's only one part of the system. At a high level, Vigilance looks like this:

┌─────────────────┐
│  React Frontend │
│   (Map & UI)    │
└────────┬────────┘
         │ REST API
         ▼
┌──────────────────────────────────────┐
│          Spring Boot Backend         │
│                                      │
│  REST Controller                     │
│         │                            │
│         ▼                            │
│  Satellite Service                   │
│         │                            │
│         ▼                            │
│   TLE Repository                     │
│         │                            │
│         ▼                            │
│   TLE State Machine                  │
│ (ACTIVE / STALE / EXPIRED)           │
│         │                            │
│         ▼                            │
│  OrbitPropagator (ACL)               │
│         │                            │
│         ▼                            │
│      Orekit                          │
│ (SGP4 + Frame Transforms)            │
└────────────────────┬─────────────────┘
                     │
              Async Refresh
                     │
                     ▼
             CelesTrak API
             (TLE Source)

Integrating Orekit with Spring Boot

Orekit isn't like most Java libraries. It needs external data files — leap seconds, Earth orientation parameters, ephemerides — loaded from the filesystem. These aren't bundled in the JAR.

@Configuration
@Slf4j
public class OrekitConfig {
    @Value("${orekit.data-path}")
    private String orekitDataPath;

    @PostConstruct
    public void init() {
        File orekitDataDir = new File(orekitDataPath);
        DataProvidersManager manager = DataContext.getDefault().getDataProvidersManager();
        manager.addProvider(new DirectoryCrawler(orekitDataDir));
        log.info("Orekit data loaded successfully from: {}", orekitDataDir.getAbsolutePath());
    }
}

I initially tried loading files from the classpath, but Orekit's DirectoryCrawler only works with real directories — it can't read inside a JAR. This broke my Docker deployment.

manager.addProvider(new DirectoryCrawler(orekitDataDir));

The fix: volume mount the data directory and configure the path via environment variables. In production, the data files live outside the container, and orekit.data-path points to the mount. This also makes updates easy — no image rebuild.

Orekit throws its own types everywhere: AbsoluteDate, PVCoordinates, Frame. I wrapped all of it in an OrbitPropagator class — the only place in the codebase that imports Orekit types. It accepts Orekit objects but returns primitive arrays: double[] with latitude, longitude, altitude, velocity. The domain layer converts those to clean Java records.

This isolation means if Orekit's API changes or I need to swap it out, I only update one file. The rest of the application doesn't care how position gets calculated — it just gets numbers.

From TLE to Real-Time Position

Here's the propagation pipeline: TLE → SGP4 algorithm → position/velocity → coordinate transformation → latitude/longitude.

Orekit uses SGP4, the standard model for converting TLEs into positions. It accounts for Earth's oblateness, atmospheric drag, and other perturbations that simple Keplerian orbits ignore.

private SpacecraftState propagate(TLE tle, AbsoluteDate date) {
    TLEPropagator propagator = TLEPropagator.selectExtrapolator(tle);
    return propagator.propagate(date);
}

public double[] getCurrentPositionAndVelocity(TLE tle, AbsoluteDate date) {
    SpacecraftState state = propagate(tle, date);
    PVCoordinates pv = state.getPVCoordinates(itrf);
    GeodeticPoint geoPoint = earth.transform(pv.getPosition(), itrf, date);
    double velocity = pv.getVelocity().getNorm() / 1000.0;

    return new double[]{
        Math.toDegrees(geoPoint.getLatitude()),
        Math.toDegrees(geoPoint.getLongitude()),
        geoPoint.getAltitude() / 1000.0,
        velocity
    };
}

The key step is transforming from ECI (Earth-Centered Inertial — fixed to the stars) to ITRF (International Terrestrial Reference Frame — rotates with Earth). That's where you get latitude and longitude.

Propagation is expensive. Each calculation involves multiple transformations and operations. I added PostgreSQL caching with intelligent invalidation — satellite data is cached for 24 hours before refresh, and position calculations are computed on-demand. This keeps the API responsive while still near-real-time.

Conclusion

I began this project thinking satellite tracking was a visualization problem. It turned out to be a data freshness problem disguised as a physics problem.

The orbital mechanics were challenging. But what surprised me most was this: the gap between a mathematical model and a production service is often larger than the gap between an idea and a prototype. Orekit gave me the physics in a few lines of code. Everything else—the state machine, the caching layer, the refresh strategy, the failure handling—took weeks.

That's where Vigilance actually lives. Not in the SGP4 algorithm. In the decisions about when to refresh, how to lock concurrent requests, what to do when CelesTrak is unreachable.

Sometimes the best way to understand a black box is to replace it.

StackFeed

From TLEs to Real-Time Satellite Tracking: Building an Orbital Backend with Spring Boot and Orekit