AI Code Assistant

A production-grade AI coding assistant web application. This project is built incrementally across phases:

• Phase 1 — Application Foundation: Flask application factory, PostgreSQL-backed models, Dockerized deployment, CI pipelines, and a test suite.
• Phase 2 — Authentication & User Management: registration, login, logout, password hashing, and account management.
• Phase 3 — AI Core Features: chat interface with streaming responses, prompt library, AI code generation and analysis tools, file upload, and conversation management.
• Phase 4 — GitHub Integration & Repository Intelligence: OAuth connection, repository browser, commit history, issues and pull requests with AI analysis, and encrypted token storage.
• Phase 5 — AI Workspaces & Project Intelligence: workspace CRUD, project import (GitHub or archive upload), lazy file explorer, project-wide search, AI project chat and analyses, and a project health dashboard.
• Phase 6 — Collaboration, AI Code Review & Quality Tooling: AI code review for pull requests and projects (quality, security, tests), structured findings with [CONFIRMED]/[SUGGESTION] labels, review history and configuration, a quality dashboard with metrics, and workspace member foundations.

Status: Phase 6 — Collaboration, AI Code Review & Quality Tooling implemented.

Table of contents

• Features
• Tech stack
• Project structure
• Getting started
  • Local development
  • Running with Docker
• Testing
• Configuration
• CI / CD
• Roadmap
• License

Features

• Flask application factory — testable, environment-driven configuration.
• User authentication — registration, login, logout, remember-me, session management, and CSRF protection via Flask-WTF.
• Secure password storage — salted hashes via Werkzeug (never plain text).
• PostgreSQL-first persistence — SQLAlchemy models with Flask-Migrate schema migrations.
• Containerized — multi-stage Dockerfile, docker-compose with a health-checked Postgres service, and a non-root runtime user.
• CI pipeline — lint (ruff), formatting (black), tests (pytest), and Docker image build on every push/PR.
• Clean UI — dark, developer-focused theme with responsive vanilla CSS and progressive-enhancement JavaScript.

Phase 2 — Authentication & user management

• Registration — create an account with a username and email; validates username length, email format, password strength (minimum 8 characters), password confirmation, and uniqueness of both username and email.
• Login & logout — email/password authentication with a remember-me option, last-login timestamp tracking, and disabled-account detection.
• Password security — salted password hashes via Werkzeug (generate_password_hash / check_password_hash); plain text is never stored.
• Session management — Flask-Login sessions with @login_required protection on authenticated routes and a shared account page (/auth/me).
• Safe redirects — post-login redirects are validated against an open-redirect attack (only same-host URLs are allowed).
• CSRF protection — all state-changing forms are protected via Flask-WTF.

Phase 3 — AI core features

• AI chat interface — per-user conversations, message history, live server-sent-event (SSE) streaming, typing indicator, and client-side Markdown rendering with code blocks.
• Prompt management — save, edit, delete, favorite, categorize, and search reusable prompt templates.
• AI code generation — generate code from natural language, plus code actions: explain, refactor, find bugs, optimize, add comments, write documentation, and draft commit messages.
• File support — upload source files and run AI analysis over their contents (multi-language, UTF-8 text).
• Conversation management — rename, pin, search, delete, and export conversations as JSON.
• Provider abstraction — a provider-agnostic LLM service layer with an offline mock provider (default) and an OpenAI-compatible client. Set LLM_PROVIDER=openai and OPENAI_API_KEY for real responses.

Phase 4 — GitHub integration & repository intelligence

• GitHub OAuth connection — connect/disconnect a GitHub account through a browser OAuth flow (scoped to read:user repo), with a signed state parameter to prevent CSRF on the callback.
• Encrypted token storage — access tokens are encrypted at rest with Fernet (AES-128 + HMAC-SHA256) using a key derived from SECRET_KEY; the plaintext token is never persisted, logged, or sent to the frontend.
• Repository browser — list and search repositories, browse branches and files (directory listing and tree view), search file names, and view file contents.
• Commit history — per-repository and per-path commit lists with author, date, and per-commit file/patch views.
• Issues — open/closed/all issue lists (pull requests excluded), issue detail pages with labels and body, and one-click AI issue analysis (summary, problem identification, suggested implementation, acceptance criteria, difficulty estimate).
• Pull requests — PR lists and detail pages with changed files and inline diffs, plus AI code review that flags potential bugs while clearly labeling [CONFIRMED] defects versus [SUGGESTION] hypotheses.
• AI repository analysis — summarize a repository from its README and structure, and ask questions about individual files. Context sent to the model is bounded (GITHUB_MAX_CONTEXT_CHARS) so a request never uploads a whole repository.
• API reliability — a dedicated GitHub API client with request timeouts, typed error taxonomy (auth, permission, not-found, rate-limit, network), exponential backoff retries on transient failures, and rate-limit awareness.
• Authorization — all GitHub API calls are made on the user's behalf with their own token, so GitHub's own permission model decides which repositories are accessible; no secrets are ever exposed to the client.

Phase 5 — AI workspaces & project intelligence

• Workspaces — per-user workspaces with create, rename, delete, and a dashboard listing projects with import status.
• Project import — import a codebase from a connected GitHub repository or an uploaded .zip / .tar.gz archive. GitHub imports walk the blob tree and fetch bounded file contents; archive extraction is done entirely in memory (nothing is written to disk).
• Import security — archive members with absolute paths, .. traversal, or symlinks are rejected/skipped; archive size, expanded size, and file-count caps (zip-bomb protection); VCS/vendor directories and secret files (.env, .pem, .key, …) are skipped; binary and oversized files keep metadata but no searchable content.
• Lazy file explorer — tree and single-file APIs load directories on demand and reject traversal paths; the file viewer shows language, size, and content with binary/oversized markers.
• Project-wide search — bounded filename and content search with literal (escaped) matching, case toggle, and match snippets; binary files are excluded from content hits.
• AI project chat — ask questions about the project; context is bounded (keyword-scored paths, key files, content fallback within a fixed character budget — never a whole-project dump) and available over SSE streaming.
• AI analyses — architecture, bug review, refactoring, test coverage, documentation, and dependency analyses. Findings are labeled [CONFIRMED] (supported by the files) versus [SUGGESTION] (inference).
• Dependency inventory — real manifests are parsed (requirements.txt, package.json, pyproject.toml, Cargo.toml, go.mod, Pipfile, Gemfile, composer.json); nothing is fabricated, and unpinned/insecure claims are surfaced only as [SUGGESTION]s.
• Prompt-injection resistance — repository file contents are explicitly framed as untrusted DATA in the system prompt, so instructions embedded in imported files are not followed.
• Health dashboard — per-project stats: file/searchable/test/doc counts, languages, dependency count, manifests, and indexing duration.

Phase 6 — Collaboration, AI code review & quality tooling

• AI PR code review — review an open pull request on a connected GitHub repository. Context is bounded (at most REVIEW_MAX_FILES changed files and REVIEW_MAX_CONTEXT_CHARS of diff text, with an optional language filter), and review runs never merge, close, approve, or otherwise modify the PR.
• Structured findings — every review returns findings with severity, category, confidence, and a file/line location (never raw repository content). Findings are labeled [CONFIRMED] (supported by the code) versus [SUGGESTION] (inference), and project reviews drop findings below the configured REVIEW_SEVERITY_THRESHOLD.
• Project reviews — run quality, security, and test-analysis reviews over an imported project; repository content is explicitly framed as untrusted data in the prompt to resist prompt injection.
• Review history & configuration — per-project review history with a config snapshot on each run, and per-project review configuration (kinds, threshold, languages, focus areas, bounds). All review routes are owner-scoped.
• Quality dashboard — aggregate metrics (review counts by status/source, findings by severity/category, addressed state, recent activity) computed strictly from stored review rows — never fabricated.
• Workspace members — WorkspaceMember model with owner/contributor/viewer roles and owner-scoped membership APIs (role assignment and removal); member-level access delegation is a planned follow-up.

Tech stack

Layer	Technology
Backend	Python 3.12, Flask 3
Database	PostgreSQL 16 (SQLite fallback for local dev)
Auth	Flask-Login, Flask-WTF, Werkzeug hashing
Migrations	Flask-Migrate (Alembic)
AI providers	Provider-agnostic service layer (mock + OpenAI)
GitHub	GitHub REST API, OAuth web flow, Fernet (cryptography)
Frontend	HTML, vanilla CSS, vanilla JavaScript (SSE)
Infrastructure	Docker, Docker Compose, GitHub Actions
Quality	pytest, ruff, black

Project structure

.
├── .github/workflows/     # GitHub Actions CI pipelines
├── app/
│   ├── auth/              # Authentication blueprint (register/login/logout)
│   ├── chat/              # Chat blueprint (conversations, SSE streaming)
│   ├── github/            # GitHub blueprint (OAuth, repo browser, issues, PRs) (Phase 4)
│   ├── main/              # Public routes, landing page, health check
│   ├── models/            # SQLAlchemy models (User, GithubAccount, ...)
│   ├── prompts/           # Prompt library blueprint (CRUD, search, favorites)
│   ├── reviews/           # AI code review blueprint (Phase 6)
│   ├── services/          # Service layer (LLM providers, GitHub API, crypto, import/search/analysis/metrics)
│   ├── static/            # CSS and JavaScript assets
│   ├── templates/         # Jinja2 templates (pages + error pages)
│   ├── tools/             # AI tools blueprint (generate, analyze, actions)
│   ├── workspaces/        # Workspaces & project intelligence blueprint (Phase 5)
│   ├── config.py          # Environment-based configuration
│   ├── extensions.py      # Shared Flask extension instances
│   └── __init__.py        # Application factory
├── migrations/            # Alembic migration scripts (generated)
├── scripts/               # Operational helper scripts
├── tests/                 # pytest suite
├── Dockerfile             # Multi-stage production image
├── docker-compose.yml     # web + postgres orchestration
├── pyproject.toml         # Tooling configuration (pytest, ruff, black)
└── requirements*.txt      # Python dependencies

Getting started

Prerequisites

• Python 3.12+
• PostgreSQL 16 (optional — SQLite is used by default in development)
• Docker + Docker Compose (optional, for containerized runs)
• Git

Local development

# 1. Clone and enter the project
git clone https://github.com/your-org/ai-code-assistant.git
cd ai-code-assistant

# 2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\activate           # Windows

# 3. Install dependencies
pip install -r requirements-dev.txt

# 4. Configure environment
cp .env.example .env             # then edit values as needed

# 5. Create the database tables (uses SQLite by default)
flask --app wsgi init-db

# 6. Run the dev server
python run.py

Open http://localhost:5000 in your browser.

Running with Docker

cp .env.example .env
docker compose up --build

• Web app: http://localhost:5000
• PostgreSQL: localhost:5432 (user aica, db aica)

The web service applies pending migrations before starting, and exposes a health check at GET /health.

Setting up GitHub OAuth (Phase 4)

1. Create an OAuth App at https://github.com/settings/applications/new:
   • Homepage URL: http://localhost:5000
   • Authorization callback URL: http://localhost:5000/github/callback
2. Copy the Client ID and Client Secret into .env:

   GITHUB_CLIENT_ID=your_client_id
   GITHUB_CLIENT_SECRET=your_client_secret

3. Restart the app and open GitHub in the navigation bar to connect your account.

Tokens are encrypted before storage and used only server-side; they are never exposed in the browser. To disconnect (and remove the stored token), use Disconnect on the GitHub dashboard.

Testing

pytest --cov=app --cov-report=term-missing

Tests run against an in-memory SQLite database so the suite is fast and self-contained. Set TEST_DATABASE_URL to a PostgreSQL URL to run the same suite against Postgres.

Configuration

All configuration is environment-driven (see .env.example):

Variable	Default	Description
APP_ENV	development	development, testing, or production
SECRET_KEY	dev-only	Flask secret — required in production
DATABASE_URL	SQLite file	SQLAlchemy connection string
SESSION_LIFETIME	43200	Session lifetime in seconds
LLM_PROVIDER	mock	LLM backend: mock (offline) or openai
OPENAI_API_KEY	unset	API key for the OpenAI provider
OPENAI_BASE_URL	OpenAI	Custom/compatible endpoint
OPENAI_MODEL	gpt-4o-mini	Model used by the OpenAI provider
MAX_CONTENT_LENGTH	16777216	Max uploaded file size in bytes
GITHUB_CLIENT_ID	unset	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	unset	GitHub OAuth app client secret
GITHUB_REDIRECT_URI	callback URL	Explicit callback URL (optional)
GITHUB_API_URL	https://api.github.com	GitHub REST API base URL
GITHUB_SCOPES	read:user repo	OAuth scopes requested on connect
GITHUB_REQUEST_TIMEOUT	30	GitHub API request timeout (seconds)
GITHUB_MAX_CONTEXT_CHARS	40000	Max repo context sent to the LLM
PROJECT_MAX_ARCHIVE_BYTES	52428800	Max uploaded project archive (50 MB)
PROJECT_MAX_SIZE_BYTES	524288000	Max expanded project size (500 MB)
PROJECT_MAX_FILE_COUNT	20000	Max files importable into one project
PROJECT_MAX_FILE_CHARS	200000	Max text content stored per file
PROJECT_MAX_CONTEXT_CHARS	40000	Max project context sent to the LLM
PROJECT_SEARCH_MAX_RESULTS	100	Max results returned by one search query
PROJECT_GITHUB_MAX_FILES	1000	Max file contents fetched per GitHub import
PROJECT_SKIP_DIRS	.git,node_modules,…	Directory basenames skipped on import
PROJECT_SKIP_SECRET_FILES	.env,.pem,…	File names/prefixes skipped on import
REVIEW_MAX_FILES	40	Max changed files analyzed in one review
REVIEW_MAX_CONTEXT_CHARS	40000	Max diff/repo context sent to the LLM per review
REVIEW_MAX_FINDINGS	100	Max findings stored per review
REVIEW_KINDS	quality,security,tests	Default project review kinds
REVIEW_SEVERITY_THRESHOLD	low	Min finding severity stored for project reviews

The production configuration fails fast at startup if SECRET_KEY or a PostgreSQL DATABASE_URL is missing — it will never silently run with insecure defaults.

The app runs fully offline with the default mock provider: chat replies, code generation, and file analysis all work with canned responses. To enable real AI responses set LLM_PROVIDER=openai and OPENAI_API_KEY (or point OPENAI_BASE_URL at an OpenAI-compatible server).

CI / CD

GitHub Actions runs on every push to main and on pull requests:

1. Lint & format — ruff check and black --check.
2. Tests — pytest with coverage reporting.
3. Docker — verifies the production image builds successfully.

Roadmap

Phases are built incrementally and tracked as GitHub issues and milestones.

Completed

• Phase 1 — Application Foundation: Flask application factory, PostgreSQL-backed models, Dockerized deployment, CI pipelines, and a test suite. ✔
• Phase 2 — Authentication & User Management: registration, login, logout, password hashing, and account management. ✔
• Phase 3 — AI Core Features: chat interface with streaming responses, prompt library, AI code generation and analysis tools, file upload, and conversation management. ✔
• Phase 4 — GitHub Integration & Repository Intelligence: OAuth connection, repository browser, commit history, issues and pull requests with AI analysis, and encrypted token storage. ✔
• Phase 5 — AI Workspaces & Project Intelligence: workspace CRUD, project import (GitHub or archive upload), lazy file explorer, project-wide search, AI project chat and analyses, and a project health dashboard. ✔
• Phase 6 — Collaboration, AI Code Review & Quality Tooling: AI code review for pull requests and projects, structured findings, review history and configuration, a quality dashboard, and workspace member foundations. ✔

Planned

• Phase 7 — Collaboration and workflow automation: workspace member access delegation, sharing, notifications, and activity feeds.

License

MIT