AI-powered codebase intelligence for understanding, analyzing, and improving software architecture.
ONGISA is a developer tool designed to give developers a clear view of how a software project is built.
It analyzes a codebase, maps its files, modules, imports, and dependencies, detects architectural problems, visualizes the structure as a dependency graph, and uses AI to help developers understand and improve the system.
Large codebases can become difficult to understand as the number of files, modules, and dependencies grows. Instead of manually searching through files and tracing connections, ONGISA builds an architectural picture of the project and helps developers answer questions such as:
- What does this file depend on?
- What depends on this module?
- Which modules are highly connected?
- Are there circular dependencies?
- Which parts of the codebase are becoming too large or complex?
- Where are the architectural smells?
- What could be refactored?
- What parts of the system could be affected by a change?
The goal: give developers an X-ray of their codebase — from structure and dependencies to architectural problems and possible improvements.
ONGISA combines several capabilities into one developer platform:
- 🔎 Static code analysis
- 📁 Repository structure analysis
- 🔗 Dependency analysis
- 🕸️ Dependency graph generation
- 📊 Code and structural metrics
- 🚨 Architectural smell detection
- 🏢 God-module detection
- 🔄 Circular dependency detection
- 🗑️ Disconnected/orphan module detection
- 📦 ZIP-based repository ingestion
- 🌐 Web-based architecture dashboard
- 🤖 Gemini-powered architecture assistance
- 💬 Conversational AI Architecture Assistant
- 📥 Markdown architecture/code audit reports
- 🔧 AI-assisted refactoring workflows
- 🐳 Docker development configuration
- ⚙️ GitHub Actions CI pipeline
ONGISA follows a pipeline that converts a software repository into an architectural model.
PROJECT
│
▼
┌─────────────────┐
│ ONGISA CORE │
└────────┬────────┘
│
▼
┌─────────────────┐
│ ANALYZE │
│ │
│ Files │
│ Functions │
│ Classes │
│ Imports │
│ Dependencies │
│ Metrics │
└────────┬────────┘
│
┌──────────┼──────────┐
▼ ▼ ▼
DEPENDENCY ARCHITECTURE CALL
GRAPH ANALYSIS ANALYSIS
│ │ │
└──────────┼──────────┘
▼
┌─────────────────┐
│ WEB DASHBOARD │
└────────┬────────┘
│
▼
┌─────────────────┐
│ GEMINI AI │
│ + RAG │
└────────┬────────┘
│
▼
AI EXPLANATIONS
│
▼
REFACTOR PLANS
ONGISA analyzes source files and extracts structural information from the project.
The analyzer can work with information such as:
- Files
- Directories
- Functions
- Classes
- Methods
- Imports
- Exports
- Symbols
- Module relationships
- Dependency relationships
- File metrics
For example:
src/
├── auth/
│ ├── login.ts
│ └── register.ts
│
├── users/
│ └── userService.ts
│
├── payments/
│ ├── payment.ts
│ └── stripe.ts
│
└── database/
└── database.ts
ONGISA does not simply treat these as isolated files.
It builds relationships between them:
login.ts
│
└──→ userService.ts
│
└──→ database.ts
payment.ts
│
└──→ stripe.ts
│
└──→ database.ts
One of ONGISA's core features is converting imports and module relationships into a visual dependency graph.
Example:
app.ts
/ \
▼ ▼
auth.ts users.ts
│ │
└───┬───┘
▼
database.ts
The graph helps developers understand:
- Which files depend on a module
- Which modules have many dependents
- Which modules are isolated
- Where dependencies are concentrated
- Where circular dependencies exist
- How changes may propagate through the project
ONGISA can also generate graph data such as:
graph.json
The web dashboard uses this information to create an interactive architecture view.
ONGISA analyzes structural relationships and metrics to identify potential architectural problems.
A God Module is a file or module that has accumulated too many responsibilities.
For example:
UserManager.ts
├── Authentication
├── Database operations
├── Email notifications
├── Payment processing
├── Validation
└── User management
ONGISA can use structural information such as:
- File size
- Symbol count
- Import count
- Dependency relationships
- Structural complexity
to identify modules that deserve investigation.
Example:
🔴 God Module Detected
File:
src/services/UserManager.ts
Metrics:
2,800 lines
67 functions
32 imports
Recommendation:
Consider separating authentication,
database access, notifications,
and user management.
ONGISA can identify dependency cycles such as:
A → B
↑ ↓
└── C
Or:
auth.ts
↓
users.ts
↓
database.ts
↓
auth.ts
Circular dependencies can make a project harder to understand, test, and modify.
ONGISA can identify files that appear disconnected from the main application dependency graph.
Example:
Application
│
├── auth.ts
├── users.ts
├── payments.ts
└── database.ts
legacyPayments.ts
A disconnected module can then be investigated to determine whether it is unused, obsolete, or intentionally isolated.
ONGISA supports analyzing uploaded project archives through the web dashboard.
The current workflow allows a developer to:
Project
│
▼
ZIP Upload
│
▼
Archive Extraction
│
▼
Source Analysis
│
▼
Dependency Graph
│
▼
Architecture Dashboard
The web application includes an upload interface for sending project archives to the backend analyzer.
Repository cloning and broader Git-based ingestion are part of the project's ongoing development.
ONGISA includes an AI layer powered by Google's Gemini API.
Rather than blindly sending an entire repository to an LLM, the AI layer works with the structured information produced by ONGISA's analysis pipeline.
The AI can reason over information such as:
- Repository structure
- Files and modules
- Symbols
- Imports
- Dependencies
- Graph relationships
- Architectural issues
- Code smells
- Analysis results
This allows ONGISA to provide architecture-focused answers grounded in the actual structure and analysis of the project, helping developers understand how different parts of the codebase are connected and where potential problems exist.
The web dashboard includes a conversational Architecture AI Assistant.
A floating chat interface allows developers to ask questions about the analyzed codebase.
Example questions:
Where is data validation handled?
Which files depend on this module?
Why is this module highly connected?
What architectural problems were detected?
Explain the current dependency structure.
What could be causing this coupling?
How could this module be refactored?
The request flows through the web application to the ONGISA AI backend and then to Gemini.
Developer Question
│
▼
Architecture Chat Drawer
│
▼
Next.js API Route
│
▼
ONGISA AI Engine
│
▼
Gemini
│
▼
Architecture Response
ONGISA can generate Markdown architecture and code audit reports from analysis results.
Reports can contain information such as:
- Total tracked files
- Dependency information
- Detected architectural issues
- Code smells
- Issue severity
- Structural recommendations
Example:
ONGISA Architecture & Code Audit Report
Overview
├── Total tracked files
├── Detected issues
└── Architectural observations
Detected Issues
├── God modules
├── Circular dependencies
└── Other structural smells
Recommendations
└── Suggested architectural improvements
Reports can be exported directly from the web dashboard.
ONGISA is designed to use analyzer results to assist with refactoring.
Instead of asking an AI model to modify a project without understanding its architecture, ONGISA first gathers structural information.
Example request:
Refactor UserManager.ts so that
authentication, database access,
and notifications are separated.
The intended workflow is:
Developer Request
│
▼
Analyzer Diagnostics
│
▼
Architecture Context
│
▼
Gemini
│
▼
Refactoring Plan
│
▼
Proposed Changes
│
▼
Developer Review
The project uses a dry-run approach so proposed changes can be inspected before being applied.
ONGISA includes a developer-facing CLI architecture.
Current commands include:
forge analyzeAnalyzes a project and generates structural and dependency information.
forge chatStarts an AI-assisted conversation with the codebase.
forge refactorRuns the refactoring workflow using analyzer diagnostics and developer instructions.
The ONGISA web dashboard is built with Next.js and React.
The dashboard provides a visual interface for exploring analyzed projects.
Current capabilities include:
- Interactive dependency topology
- Repository/project upload
- Architecture analysis
- Code smell visualization
- Dependency exploration
- Analysis results
- AI Architecture Chat Assistant
- Markdown audit report export
- Refactoring workflow interface
The dashboard is designed around the idea that developers should be able to see the architecture before changing it.
ONGISA is organized as a modular monorepo.
ONGISA/
│
├── packages/
│ │
│ ├── forge-core/
│ │ ├── schemas/
│ │ ├── models/
│ │ ├── repository/
│ │ └── cloner.py
│ │
│ ├── forge-analyzer/
│ │ ├── parsers/
│ │ ├── analysis/
│ │ ├── metrics/
│ │ ├── graph/
│ │ └── callgraph.py
│ │
│ ├── forge-ai/
│ │ ├── embeddings/
│ │ ├── retrieval/
│ │ ├── vector_store/
│ │ ├── agent.py
│ │ └── gemini/
│ │
│ └── forge-refactor/
│ ├── planning/
│ ├── transformations/
│ └── jobs/
│
├── CLI/
│ └── forge-cli/
│
├── apps/
│ └── forge-web/
│ ├── app/
│ │ └── api/
│ │ ├── chat/
│ │ ├── export/
│ │ └── graph/
│ │
│ └── components/
│ ├── DependencyGraph.tsx
│ ├── UploadDropzone.tsx
│ ├── AnalysisResult.tsx
│ └── ArchitectureChatDrawer.tsx
│
├── .github/
│ └── workflows/
│ └── ci.yml
│
├── tests/
│
├── Dockerfile
├── docker-compose.yml
└── README.md
The shared foundation of ONGISA.
Responsibilities include:
- Shared schemas
- Repository models
- AST metadata
- Analysis result structures
- Repository utilities
- Repository cloning functionality
- Shared interfaces
The static analysis engine.
Responsibilities include:
- Source parsing
- AST analysis
- Function extraction
- Class extraction
- Import analysis
- Dependency tracking
- File metrics
- Structural diagnostics
- Dependency graph generation
- Call-graph analysis
This package provides the structural intelligence used by the rest of ONGISA.
The AI intelligence layer.
Responsibilities include:
- Gemini integration
- AI architecture questions
- Codebase context construction
- Retrieval architecture
- Embeddings
- Vector storage
- AI explanations
- Architecture chat
The refactoring engine.
Responsibilities include:
- Refactoring job management
- Analyzer diagnostic integration
- AI refactoring prompts
- Transformation planning
- Dry-run workflows
- Proposed file modifications
The developer-facing terminal interface.
It provides commands such as:
forge analyze
forge chat
forge refactorThe Next.js web application.
It provides:
- Architecture visualization
- Dependency graph interaction
- Repository upload
- Analysis results
- Architecture chat
- Audit report export
- Refactoring workflows
A typical analysis session looks like this:
Developer
│
▼
ZIP Repository
│
▼
ONGISA
Source Code
↓
Parser
↓
AST / Structure
↓
Symbols + Imports + Metrics
Files
↓
Imports
↓
Dependencies
↓
Graph
Graph + Metrics
↓
Architecture Analysis
↓
├── God Modules
├── Circular Dependencies
├── Disconnected Modules
└── Other Structural Issues
Analysis Results
↓
React Flow
↓
Interactive Dashboard
Developer Question
↓
Architecture Context
↓
ONGISA AI Engine
↓
Gemini
↓
AI Explanation
Analysis Results
↓
Audit Report Generator
↓
Markdown Report
↓
Download
Architecture Problem
↓
Analyzer Diagnostics
↓
Gemini
↓
Refactoring Plan
↓
Developer Review
- Python
- FastAPI
- Pydantic
- Python AST
- Tree-sitter
- Static analysis
- Google Gemini API
google-generativeai- Retrieval-Augmented Generation architecture
- Embeddings
- Vector storage
- Next.js
- React
- TypeScript
- Tailwind CSS
- React Flow
- Python
- Typer
- Rich
- Docker
- Docker Compose
- Git
- GitHub Actions
Clone the repository:
git clone <repository-url>
cd ONGISACreate/activate the Python environment:
.\.venv\Scripts\Activate.ps1Set the Gemini API key:
$env:GEMINI_API_KEY="your_gemini_api_key"Set the Python package paths:
$env:PYTHONPATH="packages/forge-core/src;packages/forge-analyzer/src;packages/forge-ai/src"Start the backend:
uvicorn forge_ai.main:app --reload --port 8000In another terminal, start the web dashboard:
npm run dev --prefix apps/forge-webThe project can also be developed using Docker when Docker Desktop is available.
ONGISA includes automated Python tests and a Next.js build check through GitHub Actions.
The Python test suite can be run with:
$env:PYTHONPATH="packages/forge-core/src;packages/forge-analyzer/src;packages/forge-ai/src"
python -m pytest packages/forge-core/tests packages/forge-analyzer/tests packages/forge-ai/testsThe web application can be checked with:
npm run build --prefix apps/forge-webGitHub Actions is configured to automatically run project checks on pushes and pull requests.
The CI configuration is still being refined as the project evolves.
ONGISA is actively under development.
- Monorepo project structure
- Core package architecture
- Repository analysis foundation
- Static code analysis
- Import/dependency analysis
- Symbol extraction
- Dependency graph generation
- Architecture visualization
- React Flow topology dashboard
- ZIP repository upload
- Upload/dropzone interface
- Architectural smell analysis
- God-module detection
- Circular dependency analysis
- Disconnected module analysis
- FastAPI backend
- Next.js web dashboard
- Gemini AI integration
- Architecture AI chat endpoint
- Architecture Chat Drawer
- Markdown architecture report export
- Docker configuration
- GitHub Actions CI foundation
- Refactoring workflow foundation
- More robust multi-language analysis
- More advanced call-graph analysis
- Deeper cross-language dependency analysis
- More sophisticated architectural smell detection
- Improved AI/RAG reasoning
- More advanced refactoring transformations
- Improved repository ingestion
- Expanded automated test coverage
- Production-ready GitHub repository ingestion
- Multi-language parsing
- Improved AST analysis
- Better symbol resolution
- Advanced dependency tracking
- More code metrics
- More architectural smell detectors
- Module coupling analysis
- Change-impact analysis
- Dependency risk analysis
- Architecture health metrics
- Better RAG retrieval
- Architecture-aware prompting
- Deeper codebase reasoning
- Natural-language architecture exploration
- More precise refactoring recommendations
- Multi-file transformations
- Dependency-aware refactoring
- Refactoring previews
- Patch generation
- Safe rollback
- Automated tests after changes
- GitHub repository integration
- Repository history analysis
- Pull-request architecture analysis
- CI/CD integration
- Team dashboards
- Continuous architecture monitoring
ONGISA is built around a few core principles that guide how the system analyzes codebases and assists developers.
ONGISA should first understand the structure, dependencies, and architecture of a codebase before suggesting changes.
AI should work from the context produced by static analysis. Structural information should be established before AI recommendations or generation take place.
Developers should be able to understand why a particular architectural issue or refactoring is being suggested, rather than receiving unexplained changes.
Refactoring should be treated as a controlled process. ONGISA favors analysis, previews, dry runs, and developer approval before changes are applied.
ONGISA is designed to assist developers, not replace their decisions. Developers remain in control of what changes are accepted, rejected, or applied to their codebase.
As software projects grow, understanding the architecture becomes increasingly difficult.
A project can grow from:
10 files
↓
50 files
↓
500 files
↓
5,000+ files
At that point, developers may struggle to answer:
What depends on this file?
Where is this function being used?
Why is this module so large?
Are there circular dependencies?
Which modules are highly connected?
What could break if I change this?
Where should this functionality live?
How should this part of the system be refactored?
ONGISA aims to answer these questions using actual structural information from the codebase.
Traditional static-analysis tools are useful for finding individual structural problems.
AI coding assistants are useful for explaining and generating code.
ONGISA combines the two:
STATIC ANALYSIS
+
DEPENDENCY GRAPH
+
ARCHITECTURE ANALYSIS
+
CODEBASE CONTEXT
+
GENERATIVE AI
=
CODEBASE INTELLIGENCE
The analyzer provides the structural facts.
The AI provides interpretation and explanations.
Together, they create a system designed specifically around understanding software architecture.
ONGISA is currently still under active development.
License information will be added before the first official public release.
The long-term vision for ONGISA is to make large software systems easier to understand.
Instead of developers spending hours manually tracing files, imports, dependencies, and architectural problems, they should be able to ask:
"What is wrong with my architecture?"
"Why is this module so complicated?"
"What depends on this file?"
"What could be affected by this change?"
"How should I refactor this?"
"Why does this dependency exist?"
ONGISA should answer those questions using the actual architecture and structural information of the codebase, rather than guessing from isolated pieces of source code.
Analyze. Understand. Visualize. Refactor.
Your codebase has an architecture. ONGISA makes it visible.