Celestora | Flutter AI Astrology App Template

Celestora is a complete AI astrology app template built with Flutter, GetX and Material 3 — 17 screens covering the birth chart, compatibility, AI readings, a daily tarot draw, a moon calendar, a sign reference, onboarding, auth and settings, in dark and light. It casts a real natal chart on the device from a built-in ephemeris, then reads that chart through your own AI provider. Demo mode ships switched on, so every screen works with no API key and no network.

There is no astrology API behind this app. Planet positions, the ascendant, the houses and the aspects are computed in plain Dart on the phone — so there is no per-chart cost, no service that can go down, no key for your users to get, and a chart casts with the network switched off. Nothing is deployed and nothing is hosted: no server, no Firebase, no vendor SDK, and the buyer’s API keys go to the iOS keychain and to encrypted storage on Android.

What’s in the package

• Full Flutter app source code — 17 screens, null-safe, and flutter analyze comes back with zero issues
• A built-in ephemeris in plain Dart — seven bodies, twelve whole-sign houses and five aspect types, each printed with its exact orb, with no network call anywhere in the path
• Dark and light themes, declared side by side in a single app_colors.dart file, with the switch in the app on the You tab (dark, light, or follow the system)
• 186 cities bundled with their coordinates and UTC offsets, so the birth form needs no location service and no geocoding API
• Twenty-two Major Arcana with upright and reversed meanings written out, and every card face painted at run time
• Four runtime dependencies only — get, http, flutter_secure_storage and cupertino_icons. No Firebase, no charting package, no astrology package, and no vendor AI SDK, so no provider package update can break your build
• Philosopher, Hanken Grotesk and Cinzel bundled as font assets with their SIL Open Font License files, plus two subset symbol faces so the astronomical glyphs render everywhere — nothing is fetched at run time
• Clean GetX architecture — view to controller to service to data. No screen ever reads the mock layer, so replacing a service method body is all it takes to go live
• Offline HTML documentation, 19 sections — setup with and without the terminal, a terminal glossary, a screen tour with two animated walkthroughs, the ephemeris explained, provider setup, what to do when a model name is retired, renaming the app, re-theming, the project structure and troubleshooting
• 91 tests, including accuracy tests that check the ephemeris against six published astronomical events

Who is this for

• Flutter developers shipping an astrology or horoscope app who want the hard part — a real chart engine — already solved and already tested
• Freelancers and agencies with a spiritual, wellness or lifestyle client: re-skin one color file, paste the client’s key and hand it over
• Founders validating an astrology app who need something real in front of users this week, without paying a per-chart API fee before the first signup
• Product teams at horoscope, tarot and wellness brands who want a modern reference app to build on

The chart is computed, not fetched

Positions come out of an ephemeris compiled into the app: orbital elements and a Kepler solve for the planets, a periodic series for the Moon, and a precession correction so the zodiac is measured from the equinox of the date rather than from J2000. No astrology service, no per-chart fee, no rate limit. Accuracy is checked against six documented events — two total solar eclipses, the 2020 great conjunction, an equinox, a Venus transit and a Mars opposition — to a tolerance of 0.1°, six arcminutes, tighter than anything the interface shows. Those tests compare against published positions rather than against the app’s own output, because a golden file of your own numbers passes forever while being wrong.

A wheel drawn in code, not shipped as art

Twelve house sectors, a zodiac ring, the planetary glyphs at their real longitudes and the aspect web between them — one CustomPainter, no SVG, no sprite sheet, no artwork license to track. The wheel draws itself in, ring by ring, on the first cast. Tap any glyph and it pulls up that placement’s own card. Positions, Aspects and Transits are three tabs of one screen. A chart with no birth time drops the angles instead of faking them, and the wheel repaints only when the chart changes, so the same widget scales down to a list thumbnail.

The model reads the chart, not the birthday

Every placement the app computed is written into the brief in plain words — Sun at 23° Taurus in house 11, Moon conjunct Saturn, 2.3° orb — and you see the brief before it is sent. Five reading kinds ship, each with its own structure: the natal portrait, the year ahead, love and connection, work and purpose, and compatibility. One request, one reading, parsed back into titled sections: this is not a chatbot, and the model is never asked to work out where a planet is.

Two charts on one wheel

The double wheel puts one chart on the outer ring and the other on the inner, then draws only the contacts that cross between them — so a compatibility claim always points at a real aspect. Attraction, Ease, Understanding and Endurance are rated apart, in stars rather than a percentage: a single number claims a precision astrology does not have. Under the ratings sits the contact list, one row per aspect with its orb; tap a row and the two glyphs light up on the wheel above it.

A card a day, dealt from a drawn deck

The fan shuffles, you touch a card, and it turns over in 3D — an AnimatedBuilder and a rotateY transform, no packages. Twenty-two Major Arcana, every face painted from geometric motifs and astrological glyphs, so there is nothing traced and nothing licensed. Upright and reversed each have their own written meaning. The day’s card is seeded by the date, so the same day always deals the same card and a screenshot test stays repeatable.

Three AI providers, or none at all

Every call is a plain REST request written by hand — no vendor SDK, so no provider package can break the build, and nothing is proxied through a server of ours.

• Google Gemini — the shipped default. A key from AI Studio is free and needs no credit card, so your users are never sent to a billing form on their first run.
• OpenAI — strong, predictable prose. The key needs a payment method, which suits an app with paying users.
• Anthropic Claude — the most careful with a long, structured brief; it keeps every section tied to a real placement. Also pay-as-you-go.
• Demo mode — switched on out of the box. Readings are composed on the device from the chart itself, so the app answers for any birth data with no key, no network and no cost. It is not a folder of canned sample text.

Model names expire, and this template is built for that: the model id is an editable field in the app rather than a constant in the source, a retired name produces a plain-language error with a button straight to the field that fixes it, and the documentation has a section on updating it. Adding a fourth provider is one class and one catalog entry — no screen changes.

There is a whole app around the wheel

The four signature screens are the reason to buy it, but a buyer ships the rest: a month of moon phases with every day drawn as a disc rather than picked from an icon set, a reference for the twelve signs with dates, element, mode and ruler, the birth-profile form with an offline index of 186 cities and a manual UTC offset for the awkward ones, and every reading kept for later. 17 screens in all — splash, onboarding, auth, today, chart, synastry, readings, tarot, moon, signs, profiles, settings and the paywall.

Built to be handed over

A template that runs on the first try, re-skins from one file, and points at your own key without opening a single screen file. Both palettes sit side by side in app_colors.dart, every typeface is a family constant in app_text_theme.dart, and every corner radius and margin lives in app_spacing.dart — re-skinning is an afternoon, not a rewrite. There are no image assets to redraw: the wheels, the moon discs, the card faces and the sign emblems are painted, so the only bundled files are the five typefaces and their license. Views never reach into the mock layer, and every typeface is bundled rather than downloaded, so the interface renders identically offline and on a cold first launch.

Get it running in five minutes

Unzip, run flutter pub get, run flutter run. That is the whole setup — there is no server to start, no database to create, no key to register and no account to sign up for. The first thing you see is a working app in Demo mode, and you add a provider key later only if you want live readings. Every chart on every screen is cast by the app itself either way.

Try it before you buy

The Live Preview runs the real app in your browser, in Demo mode. Cast a chart and watch the wheel draw itself in, tap a glyph to read its placement, put two charts on one wheel, and turn over the card of the day — the four screens this template is built around are all clickable before you spend anything.

Requirements

To run and build the source code you need the Flutter SDK (version 3.29 or newer) and Dart 3.7 or newer, together with a Flutter-ready IDE — Android Studio or Visual Studio Code with the Flutter & Dart plugins. Runs on both Android and iOS from a single codebase. No server, no Firebase, no database.

Third-party costs and honest limits

• Third-party API costs are yours. Celestora computes charts on the device, but the written readings are produced by a third-party AI provider that you or your users supply a key for. Connecting it to a live provider — such as Google Gemini, OpenAI or Anthropic — will involve those third-party services, which will incur their own separate costs and are not included in this item. Gemini has a free tier that needs no credit card; the other two require a payment method. Demo mode is free forever and needs no key at all.
• The ephemeris is display grade. It is checked against six published events to 0.1°, which is far tighter than anything the interface prints, but it is a compact series solution rather than a full planetary theory. If you need observatory precision, the whole engine is one file to replace.
• For entertainment. The astrology and tarot content in this app is provided for entertainment. It is not medical, psychological, legal or financial advice, and the app says so where a user reads it.

What’s not included

• No backend and no bundled reading model. Written readings run against a provider you choose with your own key. Demo mode composes its text on the device from the chart itself, which is why it works offline — it is not a local language model.
• The classical seven bodies only. Sun through Saturn. Uranus, Neptune, Pluto, Chiron, the lunar nodes and the asteroids are not placed — a compact series would not place them accurately, and the classical seven are what a natal chart is read from.
• Whole-sign houses only. Placidus, Koch and the other quadrant systems are not included. Whole sign is the oldest system and it has no edge cases, which is also why a chart still draws above the polar circle.
• Five major aspects — conjunction, sextile, square, trine and opposition, each with its own orb. Minor aspects and declinations are not calculated.
• Birth profiles and reading history live in memory for the demo. They reset to the sample data on restart; only the API keys are persisted, in the iOS keychain and in encrypted storage on Android. Every service method returns a Future and touches the mock layer in exactly one place, so writing them to disk or to your API is a body swap with no screen changes.
• If secure storage is unavailable the app says so and keeps keys in memory for that session only, rather than failing silently or writing them to plain preferences.
• The paywall is a mock. Plans and an upgrade flow are wired up, but no payment code, store product or receipt validation ships — real purchases need your own.
• English only. No localization files or RTL layouts are included.

Support and updates

Questions about setup, providers, the ephemeris or re-skinning are answered through the item’s comments. Item support covers the template itself; it does not cover a provider’s own account, quota or billing.

Changelog

1.0.0 — Initial release.