Ainee - Moses Yebei

The Problem

Users need a single place to capture, organise and interrogate learning material from many formats (PDFs, audio, YouTube, etc.). Without a dedicated pipeline each source must be processed manually, leading to fragmented notes and missed insights.

What This Does

app/ implements a FastAPI‑style backend that ingests files, calls LLM services, stores results in PostgreSQL and exposes REST endpoints. The web UI lives in web/ (Next.js + React) and consumes those endpoints. A small Node crawler in web_crawler/ provides a public API for fetching remote pages.

Key files:

main.py – starts the Python service (imports app and mounts the routers).
app/api/content/index.py – core content‑creation routes (create_content, batch_create, process_transcript_task).
app/database/session.py – provides get_async_session used by 119 call sites (the database hub).
web/src/apis/index.ts – the only module that imports 97 other TS files, acting as the front‑end request façade.

How It Is Wired

Execution begins in main.py which creates a FastAPI app and includes routers from app/api/*. A typical request flow for uploading a file is:

app/api/content/index.py:create_content receives the HTTP payload.
It calls app/database/session.get_async_session (hub module – 21 callers, 1 import) to obtain a DB session.
Business logic in app/services/content_processor.py:process_file runs, which: Writes the uploaded file to the filesystem (open in app/common.py – flagged for missing context manager). Calls an LLM via app/libs/llm/ainee_web.py:invoke_llm_with_structured_output (network call). * Persists the result through app/database/repositories/content_repository.py:create (DB write).
Success or error is wrapped by the helpers in app/common.py (success, failed, failed_with_code). These helpers are the “hub module” with 27 downstream dependencies, giving them a large blast radius.

The internal call graph shows get_async_session as the most‑referenced function (119 distinct callers) and success/failed as the next‑most‑used (47/39 callers). Circular imports involve app/__init__.py, app/common.py and app/database/session.py (24 high‑severity cycles), which increase coupling and make refactoring risky.

External side‑effects traced from entry points:

Database – 118 functions issue SQL via the async session.
Network – 31 functions perform outbound HTTP (e.g., LLM calls, YouTube transcript fetch).
Filesystem – 13 functions read/write files (uploads, temporary audio extraction).
Crypto – 8 functions generate hashes or tokens (e.g., hashlib.md5 in create_upload_and_pends).

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Ainee
cd Ainee

# Install Python deps (Python 3.11 required)
pip install -r requirements.txt

# Install Node deps (pnpm required)
pnpm install --filter web...

# Spin up supporting services (Postgres, Redis) via Docker
docker compose up -d   # uses docker-compose.yml at repo root

# Run the backend
python main.py          # starts FastAPI on default port 8000

# Run the frontend (development)
cd web
pnpm dev               # starts Next.js dev server on http://localhost:3000

Environment variables are loaded from .env.example; copy it to .env and fill in database URLs, LLM API keys, etc. The Dockerfiles already pin the Python base image (python:3.11-slim‑bullseye) and the Next.js build environment.

Real‑World Use

A product manager wants to turn a recorded interview into actionable notes. They upload the audio file via the web UI → create_content stores the file, triggers process_file → the service extracts speech, calls the LLM to generate a summary and flashcards, and writes the results back to the same knowledge base. The manager can then chat with the generated notes through the /api/rag_chat endpoint.

Code Health & Issues

HIGH – No test suite – 356 source files, no tests (tests/ missing).
HIGH – No CI pipeline – no .github/workflows/ or other build gate.
HIGH – No Docker build gate – Dockerfile present but never validated automatically.
HIGH – Wildcard CORS – web_crawler/src/app.ts uses cors() with origin: "*" while credentials are enabled.
MEDIUM – Dependabot missing – three manifest files (requirements.txt, web/package.json, web_crawler/package.json) lack automated version updates.
MEDIUM – Unpinned base image – Dockerfile uses mutable tag python:3.11-slim-bullseye.
MEDIUM – Large binaries in repo – web/public/images/ai-apps-coming-soon.svg (4.9 MiB) and data/uszips-new.csv (4.8 MiB) inflate clone size.
LOW – Missing conventions – No .editorconfig, .gitattributes, or formatter config.

The Bottom Line

Ainee provides a full‑stack pipeline for AI‑augmented note‑taking, with clear separation between backend ingestion, LLM processing and a Next.js UI. The codebase is functional but suffers from high coupling (import cycles, hub modules) and a lack of automated testing/CI, which raises maintenance risk. It is suitable for teams that can invest in adding tests and refactoring the import graph; otherwise, the platform may be fragile in production.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

494 files

TypeScript138
Python122
TSX92
HTML12
JSON9
Markdown7

ReactNext.jsDocker

Module dependencies

The 10 most depended-upon modules of 355, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_app_database_session["session"] n1_src_apis_models_ResponseCode["ResponseCode"] n2_app_common["common"] n3_app___init__["__init__"] n4_app_context["context"] n5_app_database_models_content["content"] n6_ositories_content_repository["content_repository"] n7_app_config["config"] n8_app_api_file_file["file"] n9_app_database_utils["utils"] n3_app___init__ --> n7_app_config n3_app___init__ --> n8_app_api_file_file n8_app_api_file_file --> n7_app_config n8_app_api_file_file --> n2_app_common n2_app_common --> n5_app_database_models_content n5_app_database_models_content --> n0_app_database_session n6_ositories_content_repository --> n0_app_database_session n6_ositories_content_repository --> n5_app_database_models_content n6_ositories_content_repository --> n9_app_database_utils n6_ositories_content_repository --> n4_app_context n0_app_database_session --> n3_app___init__ n9_app_database_utils --> n4_app_context classDef cyc stroke:#ef4444,stroke-width:2px; class n0_app_database_session,n2_app_common,n3_app___init__,n4_app_context,n5_app_database_models_content,n6_ositories_content_repository,n8_app_api_file_file,n9_app_database_utils cyc;

Findings

MediumNo test files detected - untested code paths repository-wide
MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium3

low1

Add a test suite; this repository has nonehigh356 occurrences

356 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Add a workflow that builds and tests this repositoryhigh

356 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Add a build gate for the deployable artifacts herehigh6 occurrences

Dockerfile

deployment artifacts with no workflow

Something in the repo is meant to reach a server and no automated step has ever validated it, which is the state of 125 repositories here.

Fix: Add a workflow that at least builds the image and validates the manifests.

Replace the wildcard CORS origin with an explicit allow listhigh

web_crawler/src/app.ts

cors()

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Enable Dependabot or Renovatemedium

3 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

Dockerfile

python:3.11-slim-bullseye

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

web/public/images/ai-apps-coming-soon.svg

2 blobs over 5MB: ai-apps-coming-soon.svg 4.9MB, uszips-new.csv 4.8MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.