satyaraspi/1future

1. Overall shape

- This is a single-service FastAPI application called *Life Path Decoder*.

- It combines a browser UI, a JSON/API backend, PDF generation, lightweight persistence/config, and Railway deployment glue in one repository.

- The main architectural split is between static frontend assets in app/static/ and server-side analysis/report generation in app/.

2. Frontend presentation layer

- app/static/index.html, admin.html, styles.css, app.js, and admin.js form the client UI.

- The browser app collects user inputs such as name, DOB, time of birth, birth place, partner DOB, tone/language/report-length choices, and sharing preferences.

- The admin page is a separate UI surface at /admin for configuration and feature controls.

3. Backend API boundary

- app/main.py is the HTTP entry point and likely hosts both the HTML pages and the API endpoints.

- The API surface described in the README is:

- GET /healthz

- POST /api/analyze

- POST /api/report.pdf

- POST /api/share

- GET /api/reports

- DELETE /api/reports

- GET /api/analytics

- GET /api/config

- POST /api/config

- This boundary separates request validation/session handling from the actual report-generation logic.

4. Analysis and domain logic

- app/analyzer.py appears to hold the core “reading” engine.

- It produces Life Path / South Indian-style reflective interpretations, including:

- report summaries and detailed sections

- partner compatibility scoring

- name spelling / lucky name suggestions

- business/brand-name guidance

- trouble-with-law / compliance caution text

- selected-date prediction sections

- daily prediction logic using date/time and location context

- The README makes clear this is an entertainment/reflection engine, not a scientific or deterministic system.

5. Input enrichment and geolocation

- Birth place and visitor location are not treated as passive text; they feed into location-aware interpretation.

- The repo supports multiple geocoding paths: manual coordinates, Mapbox Temporary Geocoding, an offline India fallback, and an optional legacy public geocoder.

- “Today’s Prediction” uses approximate visitor IP location when available, which means the backend is doing location enrichment before generating some sections.

6. Report generation and export

- The backend produces multiple output forms from the same analyzed data:

- on-screen report

- TXT download

- PDF download

- share payloads for WhatsApp/Facebook/Instagram/LinkedIn-style bundles

- PDF generation uses Pillow, so the PDF pipeline is an in-process render/export step rather than a separate document service.

- The README also notes localized output in Kannada, Hindi, and Tamil, so report text generation is not just storage of language preference; it affects the actual rendered content.

7. History, analytics, and privacy controls

- The app exposes report history listing and deletion, plus analytics about report counts/types.

- There is also a “No Storage Mode” and a “Clear report history” privacy control, which suggests the backend can limit persistence or expose user cleanup actions.

- These features indicate a small stateful layer behind the stateless report-generation endpoints.

8. Admin/configuration subsystem

- /admin provides configuration for brand tagline, free plan label, premium price labels, compatibility pricing, and logo upload/preview.

- A public config endpoint is used for safe UI feature toggles, so some frontend behavior is driven by backend-provided settings.

- The admin flow includes an login dialog before opening settings, which is a distinct trust boundary from the public reading UI.

9. Security/session model

- The deployment docs emphasize SESSION_SECRET, secure cookies, idle/max session limits, and share-expiry controls.

- Demo-data creation and report history imply session-aware state, and the admin workflow is protected separately from the public app.

- “Premium unlock” is present only as a configuration/placeholder concept in this repo, not as a full external payment subsystem.

10. Deployment and runtime

- The app is designed for Railway deployment, with railway.toml, Procfile, and railway_start.py.

- run_windows.bat, run_mac_linux.sh, and their dev variants show the repo supports both production-style startup and local development with reload.

- The README’s health check path /healthz is the operational hook Railway uses to verify the service is alive.

11. Repository-level structure

- app/__init__.py marks the package, while app/main.py and app/analyzer.py divide orchestration from analysis.

- app/static/ is the only visible frontend asset boundary; there are no separate service directories or external microservices in the tree.

- patch_v150.py and the deployment/readiness scripts suggest this repo has evolved through incremental release patches and platform-specific fixes rather than a multi-service architecture.