How stebis-dev/doci works
Project Type and Purpose
• Type: Full-stack desktop application with optional cloud services, packaged via Electron and orchestrated in an Nx monorepo.
• Purpose: A cross-platform code-documentation tool (“Doci”) that parses code (via Tree-sitter), displays it in an Angular UI, imports from GitHub, and offloads heavy documentation generation to Azure Functions.
File Structure
• Top-level “apps/” contains three applications:
– angular-client (the Angular renderer UI)
– electron (the Electron main process & IPC handlers)
– renderer-e2e (Cypress tests for the UI)
• “azure/” holds serverless functions:
– githubTokenExchange.ts (OAuth token exchange)
– codeDocumentation.ts (server-side doc generation)
• “libs/shared” exposes constants and models used by both Electron and Angular.
• Services in angular-client/src/app/service cover: file system, GitHub, Tree-sitter parsing, description generation, query extraction.
README for Additional Insights
• Confirms: Nx-based monorepo, Angular + Electron dev flow, Azure Functions packaging, CI/CD workflows.
• Heavy use of Nx workflows to build, serve, and package each app.
Main Components & Their Interactions
a. Angular Renderer (apps/angular-client)
– UI components, services, and assets (Tree-sitter WASM).
– Communicates with Electron main via IPC (electron.service).
– Makes HTTP calls to Azure Functions for code documentation and token exchange.
b. Electron Main Process (apps/electron)
– Exposes IPC endpoints (api/github-auth.api.ts, main.preload.ts).
– Handles local file-system access (fileSystem.service), GitHub import (github-importer.handler), environment utilities.
– Packages the Angular bundle into a desktop app.
c. Azure Functions (azure/src/functions)
– githubTokenExchange: Exchanges OAuth codes with GitHub.
– codeDocumentation: Processes code ASTs (potentially using shared parser strategies) and returns documentation output.
d. External Services
– GitHub REST API for repo metadata and OAuth.
– (Optional) Additional external services if integrated.
e. Shared Libraries (libs/shared)
– Types, models, and constants reused by both front end and back end for type safety and consistency.
Architectural Patterns & Design Principles
• Monorepo with Nx: promotes modularity, shared code, and unified build/test scripts.
• Separation of Concerns:
– Renderer (View + client-side logic)
– Main (Platform glue, native FS, IPC, packaging)
– Serverless (Heavy compute / secure token exchange)
• IPC boundary: Clearly define channels for FS, GitHub, config, and events.
• Service abstraction: Angular services encapsulate data-fetching, parsing, theme management.