Start with A – Open-source, self-hosted investment research platform (BYOK AI)
Start with A is an open-source investment research platform integrating research, portfolio monitoring, and journaling into a disciplined workflow. It is self-hosted with BYOK AI support for Gemini, OpenAI, and Anthropic.
Notifications You must be signed in to change notification settings
Fork 0
Star 0
BranchesTags
Open more actions menu
Folders and files
NameName
Last commit message
Last commit date
Latest commit
History
658 Commits
658 Commits
.claude/skills
.claude/skills
.github/workflows
.github/workflows
app
app
data
data
docs
docs
frontend
frontend
migrations
migrations
unittests
unittests
.dockerignore
.dockerignore
.env.example
.env.example
.gitignore
.gitignore
CLAUDE.md
CLAUDE.md
Dockerfile
Dockerfile
LICENSE
LICENSE
Procfile
Procfile
README.md
README.md
architecture_notes.md
architecture_notes.md
backfill_currency.py
backfill_currency.py
backfill_sweep_kills.py
backfill_sweep_kills.py
celery_app.py
celery_app.py
config.py
config.py
database_schema.md
database_schema.md
docker-compose.yml
docker-compose.yml
docker-entrypoint.sh
docker-entrypoint.sh
init_postgresql.py
init_postgresql.py
our_vision.md
our_vision.md
package-lock.json
package-lock.json
package.json
package.json
railway.toml
railway.toml
requirements-local.txt
requirements-local.txt
requirements.txt
requirements.txt
run.py
run.py
runtime.txt
runtime.txt
setup_postgresql.py
setup_postgresql.py
stratergy.md
stratergy.md
sync_db.py
sync_db.py
vision.md
vision.md
vitest.config.js
vitest.config.js
webpack.config.js
webpack.config.js
Repository files navigation
A platform that connects research, portfolio monitoring, and journaling into one disciplined investment workflow.
See vision.md for the full product vision.
Three Parts
Research — Idea inbox, kill screening, company & sector research, AI assistant Portfolio — Position tracking, thesis vs reality, checkpoints, AI analytics Journal — Decision journal, mistake log, learning insights
Core Flow
Idea or Market Sweeper → Kill Screen → Research ←──────────────┐ → Buy Decision │ → Track Position Updated Checklist → Journal │ → Learn |───────────────┘
Tech Stack
Backend: Python 3.12, Flask, PostgreSQL (pgvector), Celery + Redis
Frontend: Jinja2 + React components, Bootstrap, Webpack
AI: Gemini, OpenAI, and Anthropic (via YAML prompt templates)
Run with Docker (recommended)
The easiest way to run the platform locally. Requires Docker and Docker Compose.
- Configure environment
cp .env.example .env
Edit .env and fill in the Auth0 and AI keys (see Environment Variables below).
DATABASE_URL and REDIS_URL are set automatically by Docker Compose — any values in .env are overridden.
- Start
docker compose up --build -d
The app will be available at http://localhost:8000.
- Services
Service Description Port
web Flask app via Gunicorn 8000
db PostgreSQL 16 + pgvector 5432
redis Redis 7 (Celery broker + cache) 6379
worker Celery background worker —
Database migrations run automatically on startup.
- Useful commands
View logs
docker compose logs -f web docker compose logs -f worker
Restart after .env changes
docker compose restart web
Stop everything
docker compose down
Stop and wipe database
docker compose down -v
- Admin access
Register an account through the UI
Ensure your email is listed in ADMIN_EMAILS in .env
Restart: docker compose restart web
Navigate to /admin
Development Setup (without Docker)
Requires Python 3.12+, PostgreSQL with the pgvector extension, Redis, and Node.js.
git clone https://github.com/warlock20/StartWithA.git cd StartWithA
Python
python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt
Frontend
npm ci && npm run build
Environment
cp .env.example .env
Edit .env — set DATABASE_URL, REDIS_URL, Auth0 keys, etc.
Database
flask db upgrade
Run
flask run
Start the Celery worker in a separate terminal:
celery -A celery_app worker --loglevel=info
Environment Variables
Copy .env.example to .env. Docker Compose sets DATABASE_URL and REDIS_URL automatically — only set those if running without Docker.
Required
Variable Description
SECRET_KEY Flask session secret — any random string
AUTH0_DOMAIN Your Auth0 tenant domain (e.g. your-tenant.auth0.com)
AUTH0_CLIENT_ID Auth0 application client ID
AUTH0_CLIENT_SECRET Auth0 application client secret
AUTH0_CALLBACK_URL OAuth callback URL (http://localhost:8000/auth/callback for Docker)
AUTH0_AUDIENCE Auth0 API audience (usually https:///userinfo)
GEMINI_API_KEY Google Gemini API key — at least one AI provider is needed
Optional
Variable Description Default
OPENAI_API_KEY OpenAI API key (alternative AI provider) —
ANTHROPIC_API_KEY Anthropic API key (alternative AI provider) —
NEWS_API_KEY NewsAPI key for market news —
ADMIN_EMAILS Comma-separated emails that get admin access —
DATABASE_URL PostgreSQL connection string set by Docker Compose
REDIS_URL Redis connection string set by Docker Compose
DEFAULT_USER_TIER Default tier for new users (free or premium) free
FLASK_DEBUG Enable debug mode False
SESSION_COOKIE_SECURE Require HTTPS for cookies True
UPLOAD_FOLDER Path for file uploads instance/uploads
Auth0 Setup
The app uses Auth0 for authentication. To set it up:
Create a free account at auth0.com
Create a Regular Web Application
In Settings, set Allowed Callback URLs to:
http://localhost:8000/auth/callback (Docker)
http://localhost:5000/auth/callback (local flask run)
Copy Domain, Client ID, and Client Secret into your .env
Hosted Version
Don't want to self-host? A managed, hosted instance is available — open a discussion to request access.
Contributing
Fork the repo and create a feature branch
Make your changes
Run the app locally to verify everything works
Open a pull request
Please keep PRs focused — one feature or fix per PR.
License
This project is licensed under the GNU Affero General Public License v3.0.
You can use, modify, and distribute this software freely. If you run a modified version on a server, you must make your source code available to users of that server. See the full license text for details.
About
Value investor's intelligence secretary
startwitha.xyz
Topics
open-source
flask
research-tool
value-investing
byok
Resources
Readme
License
AGPL-3.0 license
Uh oh!
There was an error while loading. Please reload this page.
Activity
Stars
0 stars
Watchers
0 watching
Forks
0 forks
Report repository
Releases 2
First stable version
Latest
Jul 7, 2026
+ 1 release
Packages 0
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Contributors
Uh oh!
There was an error while loading. Please reload this page.
Languages
Python 42.3%
HTML 30.7%
CSS 14.6%
JavaScript 12.4%
Mako 0.0%
Dockerfile 0.0%