Overview
========

Richy is a personal investing portfolio manager. It tracks shares,
ETFs, market indexes and cryptocurrencies; aggregates dividends,
analyst ratings and news; and computes performance, drawdown and
asset-allocation charts on top of a transactional ledger.

What Richy is
-------------

* A (passive) portfolio manager.
* A market news aggregator.
* A tool that aggregates information to help you form ideas.
* Better than your spreadsheets.

What Richy is *not*
-------------------

* A trading platform like Robinhood.
* An app that gives investing advice.
* A trading bot.
* An AI that predicts the market.

Tech stack
----------

Backend (heavy):

* `Python 3.13+ <https://www.python.org/>`_
* `Django <https://www.djangoproject.com/>`_
* `Celery <https://docs.celeryq.dev>`_
* `PostgreSQL <https://www.postgresql.org/>`_
* `Redis <https://redis.io/>`_
* `Gunicorn <https://gunicorn.org/>`_ + `Nginx <http://nginx.org/>`_
* `Graphviz <https://graphviz.org/>`_ for transaction graphs

Frontend (lightweight):

* `Pug <https://pugjs.org>`_ for templates
* `UIkit <https://getuikit.com/>`_ for the UI framework
* `Vue.js <https://vuejs.org/>`_ for a handful of interactive components
* `Highcharts <https://www.highcharts.com/>`_ for interactive charts
* `SASS <https://sass-lang.com/>`_ + `Webpack <https://webpack.js.org/>`_

Tooling:

* `uv <https://docs.astral.sh/uv/>`_ for Python dependency management
* `Ruff <https://docs.astral.sh/ruff/>`_ for lint + format
* `Sphinx <https://www.sphinx-doc.org>`_ for these docs
* GitLab CI

Repository layout
-----------------

::

    app/                       project root
    ├── app/                   the Django project
    │   ├── richy/             site package
    │   │   ├── core/          shared models, charts, scraping, paging, ...
    │   │   ├── shares/        stock shares
    │   │   ├── etfs/          ETFs
    │   │   ├── indexes/       market indexes
    │   │   ├── coins/         cryptocurrencies
    │   │   ├── transactions/  the user's portfolio
    │   │   ├── staking/       crypto staking positions
    │   │   ├── news/          news ingest + display
    │   │   ├── settings/      base.py, dev.py
    │   │   ├── celery.py      Celery app entrypoint
    │   │   ├── wsgi.py        WSGI entrypoint
    │   │   └── urls.py
    │   ├── _scripts/          fixtures / static / webpack helpers
    │   ├── gunicorn.py        gunicorn config (used by startup.sh)
    │   ├── manage.py
    │   ├── requirements       generated from pyproject.toml
    │   ├── requirements_dev   includes dev tooling
    │   └── startup.sh         container entrypoint
    ├── assets/                logo + screenshots
    ├── docs/                  this Sphinx docs tree
    ├── nginx/                 nginx config + dev certs
    ├── scripts/               release + local-CI wrappers
    ├── compose.yaml.skel      production compose template
    ├── compose.dev.yaml       development compose
    ├── compose.ci.yaml        local-CI compose stack
    ├── deploy.yaml            deployment automation
    ├── Dockerfile             production image
    ├── Dockerfile.webpack     webpack-only image
    ├── nginx.conf.skel        production nginx config template
    ├── pyproject.toml         deps + tool config
    ├── richy.service          systemd unit
    ├── uv.lock                committed lockfile
    └── .env.skel              env-var template

Where to go next
----------------

* Set up a local development environment: :doc:`local_setup`.
* Understand how Celery is configured:
  :doc:`local_setup` (for triggering tasks in dev) and
  :doc:`/architecture/tasks` (for the full schedule).
* Browse the per-app handbook: :doc:`/modules/index`.