# satyaraspi/1future architecture

> Architecture diagram of the GitHub repository satyaraspi/1future, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/satyaraspi/1future
- Repository: https://github.com/satyaraspi/1future

## Overview

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.

Main entry points: [`app/main.py`](https://github.com/satyaraspi/1future/blob/main/app/main.py) (Main app), [`app/analyzer.py`](https://github.com/satyaraspi/1future/blob/main/app/analyzer.py) (Analyzer), [`railway_start.py`](https://github.com/satyaraspi/1future/blob/main/railway_start.py) (Railway start), [`app/static/index.html`](https://github.com/satyaraspi/1future/blob/main/app/static/index.html) (Public page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend UI"]
  node_public_html["Public page<br/>HTML shell<br/>[index.html]"]
  node_public_js["Client app<br/>frontend logic<br/>[app.js]"]
  node_admin_html["Admin page<br/>HTML shell<br/>[admin.html]"]
  node_admin_js["Admin client<br/>frontend logic<br/>[admin.js]"]
  node_styles_css["Styles<br/>shared CSS<br/>[styles.css]"]
end

subgraph group_backend["Backend App"]
  node_app_main_py["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_app_analyzer_py["Analyzer<br/>analysis engine<br/>[analyzer.py]"]
  node_api_surface(("API routes<br/>HTTP boundary"))
  node_report_generation["Report export<br/>render/export"]
  node_location_enrichment{{"Location enrich<br/>geo/context"}}
  node_history_store[("Report history<br/>state/persistence")]
  node_config_admin["Config admin<br/>settings"]
  node_share_payloads["Share bundles<br/>social export"]
end

subgraph group_ops["Deployment"]
  node_railway_start["Railway start<br/>startup script<br/>[railway_start.py]"]
  node_railway_toml["Railway config<br/>deploy config<br/>[railway.toml]"]
  node_procfile["Procfile<br/>process config"]
  node_run_scripts["Run scripts<br/>local startup"]
end

node_public_js -->|"calls APIs"| node_app_main_py
node_admin_js -->|"configures"| node_app_main_py
node_public_html -->|"loads"| node_public_js
node_admin_html -->|"loads"| node_admin_js
node_public_html -->|"uses"| node_styles_css
node_admin_html -->|"uses"| node_styles_css
node_app_main_py -->|"hosts"| node_api_surface
node_app_main_py -->|"invokes"| node_app_analyzer_py
node_app_main_py -->|"orchestrates"| node_report_generation
node_app_main_py -->|"enriches"| node_location_enrichment
node_app_main_py -->|"persists"| node_history_store
node_app_main_py -->|"serves"| node_config_admin
node_app_main_py -->|"prepares"| node_share_payloads
node_app_analyzer_py -->|"feeds"| node_report_generation
node_location_enrichment -->|"context for"| node_app_analyzer_py
node_history_store -.->|"governed by"| node_config_admin
node_railway_start -->|"starts"| node_app_main_py
node_procfile -->|"launches"| node_railway_start
node_railway_toml -->|"deploys"| node_procfile
node_run_scripts -.->|"mirrors"| node_railway_start

click node_app_main_py "https://github.com/satyaraspi/1future/blob/main/app/main.py"
click node_app_analyzer_py "https://github.com/satyaraspi/1future/blob/main/app/analyzer.py"
click node_public_html "https://github.com/satyaraspi/1future/blob/main/app/static/index.html"
click node_public_js "https://github.com/satyaraspi/1future/blob/main/app/static/app.js"
click node_admin_html "https://github.com/satyaraspi/1future/blob/main/app/static/admin.html"
click node_admin_js "https://github.com/satyaraspi/1future/blob/main/app/static/admin.js"
click node_styles_css "https://github.com/satyaraspi/1future/blob/main/app/static/styles.css"
click node_railway_start "https://github.com/satyaraspi/1future/blob/main/railway_start.py"
click node_railway_toml "https://github.com/satyaraspi/1future/blob/main/railway.toml"
click node_procfile "https://github.com/satyaraspi/1future/tree/main/Procfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_html,node_public_js,node_admin_html,node_admin_js,node_styles_css toneBlue
class node_app_main_py,node_app_analyzer_py,node_api_surface,node_report_generation,node_location_enrichment,node_history_store,node_config_admin,node_share_payloads toneAmber
class node_railway_start,node_railway_toml,node_procfile,node_run_scripts toneMint
```

## Components

### Frontend UI

Browser surfaces and shared static assets

- [Public page](https://github.com/satyaraspi/1future/blob/main/app/static/index.html): HTML shell · Main browser UI for entering birth and preference data · `app/static/index.html`
- [Client app](https://github.com/satyaraspi/1future/blob/main/app/static/app.js): frontend logic · Collects inputs and calls the analysis and report APIs · `app/static/app.js`
- [Admin page](https://github.com/satyaraspi/1future/blob/main/app/static/admin.html): HTML shell · Separate admin surface for configuration and feature controls · `app/static/admin.html`
- [Admin client](https://github.com/satyaraspi/1future/blob/main/app/static/admin.js): frontend logic · Drives admin login and settings workflows · `app/static/admin.js`
- [Styles](https://github.com/satyaraspi/1future/blob/main/app/static/styles.css): shared CSS · Shared visual styling for public and admin surfaces · `app/static/styles.css`

### Backend App

HTTP entrypoint and analysis/report pipeline

- [Main app](https://github.com/satyaraspi/1future/blob/main/app/main.py): FastAPI entrypoint · Serves pages and exposes API endpoints · `app/main.py`
- [Analyzer](https://github.com/satyaraspi/1future/blob/main/app/analyzer.py): analysis engine · Generates readings, compatibility, naming, and daily prediction text · `app/analyzer.py`
- **API routes**: HTTP boundary · Health, analyze, report, share, report history, analytics, and config endpoints
- **Report export**: render/export · Builds on-screen reports plus TXT and PDF output
- **Location enrich**: geo/context · Resolves birth place and visitor location for context-aware sections
- **Report history**: state/persistence · Stores, lists, clears, and analyzes saved reports
- **Config admin**: settings · Public config and protected admin controls for branding and plan flags
- **Share bundles**: social export · Prepares shareable payloads for external channels

### Deployment

Railway and local startup glue

- [Railway start](https://github.com/satyaraspi/1future/blob/main/railway_start.py): startup script · Launches the app for Railway runtime · `railway_start.py`
- [Railway config](https://github.com/satyaraspi/1future/blob/main/railway.toml): deploy config · Defines Railway service deployment settings · `railway.toml`
- [Procfile](https://github.com/satyaraspi/1future/tree/main/Procfile): process config · Declares the production process entrypoint · `Procfile`
- **Run scripts**: local startup · Platform-specific helpers for local and dev startup

## Connections

- Client app → Main app: calls APIs · Submits analysis and report requests
- Admin client → Main app: configures · Reads and updates backend settings
- Public page → Client app: loads · Main page bootstraps client behavior
- Admin page → Admin client: loads · Admin page bootstraps admin behavior
- Public page → Styles: uses · Applies shared UI styling
- Admin page → Styles: uses · Applies shared UI styling
- Main app → API routes: hosts · Defines HTTP endpoints and page serving
- Main app → Analyzer: invokes · Delegates reading generation to the analyzer
- Main app → Report export: orchestrates · Turns analyzed data into TXT/PDF outputs
- Main app → Location enrich: enriches · Resolves geo context before analysis
- Main app → Report history: persists · Manages report history and analytics
- Main app → Config admin: serves · Exposes public config and admin settings
- Main app → Share bundles: prepares · Builds shareable report bundles
- Analyzer → Report export: feeds · Produces structured content consumed by exports
- Location enrich → Analyzer: context for · Adds birthplace and visitor location signals
- Report history → Config admin: governed by · Storage behavior is affected by privacy and config controls
- Railway start → Main app: starts · Bootstraps the FastAPI service on Railway
- Procfile → Railway start: launches · Declares runtime command for deployment
- Railway config → Procfile: deploys · Coordinates Railway service configuration
- Run scripts → Railway start: mirrors · Local scripts follow the same startup path