feat: performance optimizations, schematic API, and branching setup

[mbaneshi]

Summary

• Fix 4 N+1 query patterns in communities, processes, ask context, and skip chapter — replaced per-row loops with batch queries + HashMap grouping
• Add 6 missing DB indexes on FK columns (migration 0010) for community_members, process_steps, chapters, chapter_sections, progress
• Add pagination (limit/offset) to files, symbols, narratives repos and API routes (default 50, max 200)
• Expand moka cache 100→500 entries, add caching to files/symbols list endpoints
• Add HTTP Cache-Control middleware (public, max-age=300) for all GET API routes
• Add schematic API — /api/v1/schematic with depth-limited lazy loading, expand, and detail endpoints
• Add client-side fetch cache in api.ts — 5min TTL for read-heavy endpoints (files, symbols, communities, narratives, chapters)
• Rewrite schematic frontend — remove ELK.js (1.5MB), replace with pure-TS layout engine (159 LOC)
• Add vite brotli compression + manual chunk splitting for three.js, 3d-force-graph, shiki
• Lazy-load Shiki languages per file instead of all upfront
• Adopt feature branch workflow — dev branch, CI triggers on dev+main, delete-branch-on-merge enabled

Test plan

• cargo build && cargo clippy && cargo test — zero warnings, all 47 suites pass
• Verify paginated endpoints: GET /api/v1/symbols?limit=10&offset=0
• Verify N+1 fix: GET /api/v1/communities returns data in 2 queries (not 1+N)
• Check Cache-Control header on GET responses
• Frontend: verify cached fetches don't re-request within 5min window
• cd frontend && pnpm build — verify brotli-compressed chunks created

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request delivers a comprehensive suite of performance optimizations and introduces a powerful new schematic API to enhance the application's responsiveness and user experience. By addressing database inefficiencies, implementing robust caching strategies, and revamping the frontend architecture for the schematic view, the changes significantly improve data loading times and reduce client-side resource consumption. The new schematic API provides a unified, lazy-loaded, and interactive way to explore the codebase, laying the groundwork for more integrated features.

Highlights

• Performance Optimizations: Addressed 4 N+1 query patterns in communities, processes, ask context, and skip chapter by replacing per-row loops with batch queries and HashMap grouping.
• Database Indexing: Introduced 6 missing database indexes on foreign key columns (community_members, process_steps, chapters, chapter_sections, progress) via migration 0010 to improve query performance.
• API Pagination: Implemented pagination (limit/offset) for files, symbols, and narratives API routes, with a default limit of 50 and a maximum of 200.
• Caching Enhancements: Expanded the backend Moka cache capacity from 100 to 500 entries and added caching to files/symbols list endpoints. Also, implemented client-side fetch caching in api.ts with a 5-minute TTL for read-heavy endpoints.
• HTTP Caching: Added an HTTP Cache-Control middleware (public, max-age=300) for all GET API routes to leverage browser caching.
• New Schematic API: Introduced a new /api/v1/schematic API with endpoints for depth-limited lazy loading, node expansion, and detailed information, providing a unified view of the codebase.
• Frontend Schematic Rewrite: Rewrote the schematic frontend, removing the 1.5MB ELK.js library and replacing it with a pure-TS layout engine (159 LOC) for improved performance and reduced bundle size.
• Frontend Build Optimizations: Added Vite Brotli compression and manual chunk splitting for large dependencies like three.js, 3d-force-graph, and Shiki. Shiki languages are now lazy-loaded per file instead of all upfront.
• Workflow Adoption: Adopted a feature branch workflow, including a dev branch, CI triggers on dev and main, and enabled delete-branch-on-merge.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Ignored Files

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/ci.yml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

The pull request introduces significant performance optimizations across the backend API, addressing N+1 query problems, adding pagination, and expanding caching mechanisms. The new schematic API and its frontend rewrite are major improvements, replacing a heavy third-party library with a lean, custom solution. Database migrations for new indexes and client-side caching further enhance performance. The documentation for optimizations and the architectural decision record are excellent additions, providing clear rationale and future plans. However, there are a few minor issues related to error handling and a potential bug in the new schematic repository, as well as a stale entry in package.json.

[gemini-code-assist]

In the loop for creating intermediate directory nodes, parts[i].to_string() seems incorrect. parts is the split array of the full path, and i is the index of the current part being processed. It should likely be part.to_string() to use the current part variable from the for loop.

Suggested change

	label: parts[i].to_string(), parent_id: Some(parent_id.clone()),
	label: part.to_string(), parent_id: Some(parent_id.clone()),

[gemini-code-assist]

Using .unwrap() for conn.prepare can lead to a panic if the SQL statement is malformed or there's a database issue. It's generally safer to handle the Result explicitly, perhaps by mapping it to an ApiError.

Suggested change

	let mut stmt = conn.prepare(&sql).unwrap();
	let mut stmt = conn.prepare(&sql).map_err(|e| ApiError::from(codeilus_core::error::CodeilusError::Database(Box::new(e))))?;

[gemini-code-assist]

Similar to the prepare call, using .unwrap() on stmt.query_map can cause a panic if the query execution fails. It's best to handle this Result explicitly to provide a more robust error response.

        let rows = stmt.query_map(params.as_slice(), |row| {
            Ok((
                row.get::<_, String>(0)?,
                row.get::<_, String>(1)?,
                row.get::<_, String>(2)?,
                row.get::<_, i64>(3)?,
                row.get::<_, i64>(4)?,
                row.get::<_, Option<String>>(5)?,
            ))
        }).map_err(|e| ApiError::from(codeilus_core::error::CodeilusError::Database(Box::new(e))))?;

[gemini-code-assist]

The sideEffects entry for ./src/lib/schematic/elk-layout.ts should be removed. The elk-layout.ts file was removed in this PR, making this entry stale and potentially misleading for bundlers.

  "scripts": {