cjp2600/protoc-gen-structify

1. What this repo is

protoc-gen-structify is a Go Protocol Buffers plugin. Its job is to read .proto definitions annotated with structify options and generate typed database-access code, rather than an application runtime or server.

2. Overall flow

The architecture is a one-way code-generation pipeline:

protobuf schema + custom structify options → plugin parses descriptors and model state → provider-specific code generation → Go source files for DB clients, storage/query helpers, constants, and relation handling.

3. Plugin entrypoint

The top-level main.go and plugin/plugin.go form the protoc plugin boundary. This is the executable that protoc invokes, and it delegates into the internal generator logic rather than talking to any database directly.

4. Schema/options layer

plugin/options/structify.proto and the generated structify.pb.go define the custom protobuf annotations used to describe tables, primary keys, foreign keys, relations, and provider selection. These options are the main input contract for generation.

5. Generation core

plugin/generator is the central orchestration layer. It turns protobuf descriptors and parsed metadata into output files, and its tests indicate this is where the main generation semantics are validated.

6. Provider abstraction

plugin/provider/provider.go defines the abstraction for database backends, with concrete implementations for:

- plugin/provider/postgres

- plugin/provider/sqlite

- plugin/provider/clickhouse

This is the main architectural boundary in the repo: database-specific SQL dialect and behavior are isolated behind provider packages.

7. Provider-specific templating

Each provider has its own templater and tmpl directories. The templater packages assemble generation inputs, while the tmpl packages hold the actual code templates for init logic, table code, and condition helpers. This keeps SQL-generation differences localized per database engine.

8. Import/state plumbing

plugin/import manages generated import sets, avoiding duplication and keeping output files consistent. plugin/state stores generation-time context across files/messages, likely tracking resolved tables, relations, and naming decisions while the plugin traverses the schema.

9. Utility and versioning

plugin/pkg/helper contains shared helper logic used across generation, and plugin/pkg/version exposes version metadata. These are supporting packages rather than architectural pillars, but they help stabilize output and tooling behavior.

10. Repository examples as architecture samples

The example/ tree is important because it shows the generated-code boundary in practice. The case_one, case_two, and case_click examples include generated *.db.go files alongside .proto inputs and small Go programs that exercise CRUD, pagination, and relation queries. They demonstrate the expected contract between schema, generator, and application code.

11. Database feature coverage

The README and example layout show that the generated layer supports CRUD, filtering, pagination, transactions, joins, and relation navigation. ClickHouse is treated differently from the row-oriented providers because it supports query settings and PREWHERE, which is reflected in the separate ClickHouse provider implementation.

12. Tests as architecture guardrails

The repo has focused tests around the generator, imports, helper utilities, state management, and each provider. That suggests the system is designed around deterministic code generation, with tests protecting both cross-provider behavior and backend-specific output.

13. What is not in scope

This repo does not appear to include a live database service, HTTP server, or ORM runtime. The generated code is the output artifact; the only runtime dependency is the consumer application that imports the generated package and passes in a database connection.

14. Diagram-friendly boundary summary

For an architecture diagram, the main boxes are: protobuf schema + structify options, protoc plugin entrypoint, generator/state/import orchestration, provider implementations per database, template/rendering layer, and generated Go DB-access code consumed by example apps.