11# 🤖 CodeScribeAI
22
33CodeScribeAI is a local-first coding assistant with:
4+
45- FastAPI backend
56- React + Vite frontend
67- GitHub repository analysis
78- Ollama-powered AI responses
89
910## Current Architecture
11+
1012- Backend: ` main.py ` (FastAPI)
1113- Frontend: ` frontend/ ` (React, Vite)
1214- Session store: SQLite (` sessions.db ` )
1315- Optional async workers: Celery + Redis
1416
1517## Prerequisites
18+
1619- Python 3.10+
1720- Node.js 18+
1821- Ollama installed and running
1922- (Optional) Redis for async chat endpoints
2023
2124## Environment Setup
25+
22261 . Copy ` .env.example ` to ` .env `
23272 . Fill real credentials and secrets
2428
@@ -27,12 +31,15 @@ cp .env.example .env
2731```
2832
2933Required keys:
34+
3035``` env
3136APP_ENV=development
3237SECRET_KEY=replace-with-a-long-random-string
3338FRONTEND_URL=http://localhost:5173
3439SESSION_TTL_SECONDS=3600
40+ SESSION_STORE_TYPE=sqlite # or "redis"
3541SESSIONS_DB_PATH=sessions.db
42+ REDIS_URL=redis://localhost:6379/0
3643GITHUB_CLIENT_ID=your_github_client_id
3744GITHUB_CLIENT_SECRET=your_github_client_secret
3845GITHUB_TOKEN=your_github_token
@@ -42,42 +49,60 @@ OLLAMA_FALLBACK_MODELS=
4249```
4350
4451Optional async keys:
52+
4553``` env
4654CELERY_BROKER_URL=redis://localhost:6379/0
4755CELERY_RESULT_BACKEND=redis://localhost:6379/0
4856```
4957
5058## Install
59+
5160### Backend
61+
5262``` bash
5363# from repo root
5464python -m venv venv
5565# Windows PowerShell
5666.\v env\S cripts\A ctivate.ps1
57- pip install fastapi uvicorn httpx python-dotenv itsdangerous pydantic celery
67+ pip install -r requirements.txt
68+ ```
69+
70+ ### Pre-commit (format + lint hooks)
71+
72+ ``` bash
73+ # after installing requirements
74+ pre-commit install
75+ pre-commit run --all-files
5876```
5977
78+ (If you're using a different shell, use the same commands with the appropriate activation step.)
79+
6080### Frontend
81+
6182``` bash
6283cd frontend
6384npm install
6485```
6586
6687## Run Locally
88+
6789### 1) Start Ollama
90+
6891``` bash
6992ollama serve
7093ollama pull phi3:mini
7194```
7295
7396### 2) Start backend
97+
7498``` bash
7599# from repo root
76100.\v env\S cripts\A ctivate.ps1
77101uvicorn main:app --reload --host 127.0.0.1 --port 8000
78102```
79103
80104### 3) Start frontend
105+
81106``` bash
82107cd frontend
83108npm run dev
@@ -86,6 +111,7 @@ npm run dev
86111Open: ` http://localhost:5173 `
87112
88113## Optional: Async Worker (Celery)
114+
89115Only needed if you use async task endpoints.
90116
91117``` bash
@@ -95,18 +121,22 @@ celery -A main:celery_app worker --loglevel=info --pool=solo
95121```
96122
97123## Testing and Quality
124+
98125### Backend tests
126+
99127``` bash
100128python -m unittest discover -s tests -v
101129```
102130
103131### Frontend lint
132+
104133``` bash
105134cd frontend
106135npm run lint
107136```
108137
109138## Key API Endpoints
139+
110140- ` GET /health `
111141- ` GET /api/ai-status `
112142- ` POST /api/chat `
@@ -116,11 +146,13 @@ npm run lint
116146- ` GET /repos/{owner}/{repo}/file-content?path=... `
117147
118148## Security Notes
149+
119150- Never commit ` .env ` .
120151- Rotate any leaked credentials immediately.
121152- For non-development environments:
122153 - set a strong ` SECRET_KEY `
123154 - use secure deployment secrets management
124155
125156## Production Readiness
157+
126158See ` PRODUCTION_READINESS.md ` for checklist and current status.
0 commit comments